The way to contribute to tutorials

Anything and everything that's related to OGRE or the wider graphics field that doesn't fit into the other forums.
Post Reply
User avatar
BohdanKornienko
Halfling
Posts: 43
Joined: Sat Nov 01, 2014 10:26 pm

The way to contribute to tutorials

Post by BohdanKornienko »

Hello!
This question is more to developers of the engine.

I am currently getting into OGRE itself and trying to use wiki. There are some issues with materials there and they can be fixed.

Here http://www.ogre3d.org/forums/viewtopic.php?f=1&t=91762 @paroj suggest to use doxygen for tutorials.

I am learning ogre 1.10. And I was wonder what is the way to contribute to the section of tutorials into this documentation?

Since I will do all those notes and stuff for myself it also could be useful for anyone else.
paroj
OGRE Team Member
OGRE Team Member
Posts: 1994
Joined: Sun Mar 30, 2014 2:51 pm
x 1074
Contact:

Re: The way to contribute to tutorials

Post by paroj »

take a look at e.g. https://github.com/OGRECave/ogre/blob/m ... s/setup.md

basically it is just markdown that you can preview with whatever editor you like. To fully build the doc to check cross-references and doxygen extensions build the OgreDoc target as "make OgreDoc".

To finally contribute your changes, just use pull-request as you would do with code:
https://github.com/OGRECave/ogre/pull/488
User avatar
BohdanKornienko
Halfling
Posts: 43
Joined: Sat Nov 01, 2014 10:26 pm

Re: The way to contribute to tutorials

Post by BohdanKornienko »

Thanks paroj for answer.
I have noticed that you also have repository at GitHub apart of BitBucket.

I wonder if these two synchronized somehow.
I mean in which one is better to contribute?
paroj
OGRE Team Member
OGRE Team Member
Posts: 1994
Joined: Sun Mar 30, 2014 2:51 pm
x 1074
Contact:

Re: The way to contribute to tutorials

Post by paroj »

both are synchronized. Its better to contribute via github due to better merge request handling over there - unless you have to learn git first to do so..
User avatar
BohdanKornienko
Halfling
Posts: 43
Joined: Sat Nov 01, 2014 10:26 pm

Re: The way to contribute to tutorials

Post by BohdanKornienko »

I have created docs and would like to make pull request on GitHub repository.
But when I am doing push of the branch with changes I ah getting Permission denied message.

I guess I am missing some steps here.
Could you help me with it?
paroj
OGRE Team Member
OGRE Team Member
Posts: 1994
Joined: Sun Mar 30, 2014 2:51 pm
x 1074
Contact:

Re: The way to contribute to tutorials

Post by paroj »

you have to push your changes to your fork, see:
https://guides.github.com/activities/forking/

if you did not create a fork yet, you will have to change the remote of your local repository as:
https://help.github.com/articles/changi ... ote-s-url/
User avatar
BohdanKornienko
Halfling
Posts: 43
Joined: Sat Nov 01, 2014 10:26 pm

Re: The way to contribute to tutorials

Post by BohdanKornienko »

Made my first pull request:
https://github.com/OGRECave/ogre/pull/512

Hopefully did not do anything wrong. Will appreciate for add remarks and recommendations.
paroj
OGRE Team Member
OGRE Team Member
Posts: 1994
Joined: Sun Mar 30, 2014 2:51 pm
x 1074
Contact:

Re: The way to contribute to tutorials

Post by paroj »

thanks for contributing, your tutorials are now online:
https://ogrecave.github.io/ogre/api/1.1 ... Scene.html
User avatar
BohdanKornienko
Halfling
Posts: 43
Joined: Sat Nov 01, 2014 10:26 pm

Re: The way to contribute to tutorials

Post by BohdanKornienko »

Wow! That is awesome!

I am going to continue adding tutorials to repository. So there are going to be more.
User avatar
BohdanKornienko
Halfling
Posts: 43
Joined: Sat Nov 01, 2014 10:26 pm

Re: The way to contribute to tutorials

Post by BohdanKornienko »

paroj wrote:thanks for contributing, your tutorials are now online:
https://ogrecave.github.io/ogre/api/1.1 ... Scene.html
I looked through the diff you have made. And I have several comments. Please do not take them offensively. I am open to discuss all the following.

I see that you reorganized the structure of the tutorials.
Does it mean that all Basic Tutorials now has to go into this "Getting Started" section?
I assume there should be another section for "advanced" tutorials as well.

Note. Bullet with "basictutorials" left on the Tutorials page.

I also think it is better to have references on which material to study next.
Maybe it is better to return references like "What to learn next". Person which will study OGRE should have some road-map for that.

The structure of Basic, Advance, etc. tutorials on the wiki is a good one. It helped me to focus on relevant things first when I started with OGRE.

By removing TutorialApplication.cpp the learner now will be confused in which part of the setup method he should add the code from "Your First Scene" tutorial. Beginning of this tutorial assumes that user will start with TutorialApplication.cpp. We should either rewrite "Your First Scene" tutorial (at least first part of it) or return that cpp file back.

It would be great to have strategy of Tutorials improvement.

Cheers!
paroj
OGRE Team Member
OGRE Team Member
Posts: 1994
Joined: Sun Mar 30, 2014 2:51 pm
x 1074
Contact:

Re: The way to contribute to tutorials

Post by paroj »

BohdanKornienko wrote: Does it mean that all Basic Tutorials now has to go into this "Getting Started" section?
I assume there should be another section for "advanced" tutorials as well.
yes and yes :) However I do not like empty structures, so I would introduce "advanced" only when we get the respective tutorial.
BohdanKornienko wrote: I also think it is better to have references on which material to study next.
Maybe it is better to return references like "What to learn next". Person which will study OGRE should have some road-map for that.
to me it seemed obvious that the next thing is the next topic in the sidebar on the left. Also I did not like that one has to manage the references manually.
BohdanKornienko wrote: By removing TutorialApplication.cpp the learner now will be confused in which part of the setup method he should add the code from "Your First Scene" tutorial. Beginning of this tutorial assumes that user will start with TutorialApplication.cpp. We should either rewrite "Your First Scene" tutorial (at least first part of it) or return that cpp file back.
It was duplicating the setup page too much. We should rather extend that one to fit the needs.
https://ogrecave.github.io/ogre/api/1.10/setup.html

Note that I prefer to avoid duplication at the cost of completeness here, since adding new content is always easier then merging large amount of text. (+ keeping duplicated text in sync)
While at it: "Your first Scene" duplicates the manual quite a lot:
https://ogrecave.github.io/ogre/api/1.1 ... jects.html

We should work out where to draw the line between Manual/ Tutorial as well.
User avatar
BohdanKornienko
Halfling
Posts: 43
Joined: Sat Nov 01, 2014 10:26 pm

Re: The way to contribute to tutorials

Post by BohdanKornienko »

paroj wrote:
BohdanKornienko wrote: Does it mean that all Basic Tutorials now has to go into this "Getting Started" section?
I assume there should be another section for "advanced" tutorials as well.
yes and yes :) However I do not like empty structures, so I would introduce "advanced" only when we get the respective tutorial.
Agree. Empty structures are not that good. Anyway, since I am rookie here, I just wanted to know which direction all this has to develop.
paroj wrote:
BohdanKornienko wrote: I also think it is better to have references on which material to study next.
Maybe it is better to return references like "What to learn next". Person which will study OGRE should have some road-map for that.
to me it seemed obvious that the next thing is the next topic in the sidebar on the left. Also I did not like that one has to manage the references manually.
Makes sense. How about some general overview which way person has to learn the engine? Somewhere in a one place. And there could be info which material to learn first.
I still believe that person has to have some guide over materials :D
paroj wrote:
BohdanKornienko wrote: By removing TutorialApplication.cpp the learner now will be confused in which part of the setup method he should add the code from "Your First Scene" tutorial. Beginning of this tutorial assumes that user will start with TutorialApplication.cpp. We should either rewrite "Your First Scene" tutorial (at least first part of it) or return that cpp file back.
It was duplicating the setup page too much. We should rather extend that one to fit the needs.
https://ogrecave.github.io/ogre/api/1.10/setup.html
I see. The first tutorial is still required rewriting in this context. I will try fix it so that it will use Bootstrap example as a base when I continue with tutorials porting.
paroj wrote:
Note that I prefer to avoid duplication at the cost of completeness here, since adding new content is always easier then merging large amount of text. (+ keeping duplicated text in sync)
While at it: "Your first Scene" duplicates the manual quite a lot:
https://ogrecave.github.io/ogre/api/1.1 ... jects.html

We should work out where to draw the line between Manual/ Tutorial as well.
Agree. Did no consider Bootstrap as a part of tutorials.
Post Reply