The state of Ogre's documentation

Discussion area about developing or extending OGRE, adding plugins for it or building applications on it. No newbie questions please, use the Help forum for that.
Oogst
OGRE Expert User
OGRE Expert User
Posts: 1067
Joined: Mon Mar 29, 2004 8:49 pm
Location: the Netherlands
x 43
Contact:

The state of Ogre's documentation

Post by Oogst »

I get the idea that Ogre's documentation is slowly getting into quite a bad state, and I am wondering whether others agree with me on this and something should be done, or whether I just bumped into some random things and it is still good overall.

I have been using Ogre for over 9 years now and recently came back to it after two years of hardly using it. Some of the things I noticed in the past few weeks:

-This tutorial about integrated depth shadows was so broken that I needed help from an Ogre dev to get it to work.
-The part in the Manual about Overlays has not been updated with that Overlay's are now a component and need to be initialised to use them.
-The porting notes do not mention that "Plugins.cfg" has been renamed to "Plugins_d.cfg" in Ogre 1.9 for debug mode.
-The example file "HardwareSkinningShadow.material" contains a reference to a shader "shadow_receiver_vs" in the file "HardwareSkinningShadow.cg", but this shader does not exist there.
-The samples have so many options and thingies that it is really difficult to see in their source code how to actually achieve some effect. The samples are fine for showing off Ogre, but pretty bad as examples of how to actually use Ogre. I think there should be a large set of mini-applications that do only one thing in the absolute minimal way, to make it much easier to learn how to do things from that.
-The Wiki has so many tutorials and articles on the same subjects that it is difficult to figure out which to use. Tons of those seem out-of-date. I think these need to be cleaned up.
-The Manual mostly focusses on syntax and theory, but hardly on how to actually do things. I think articles in the Manual should link to Tutorials and Samples that should how to actually use what you just read about.

I think documentation and learning curve are at least as important as features. However, when I looked at the plans for the future of Ogre, I only see improvements to the engine itself. Isn't it time for a big push in improving documentation and learning curve?
My dev blog
Awesomenauts: platforming MOBA (PC/Mac/Linux/XBox360/X1/PS3/PS4)
Blightbound: coop online dungeon crawler (PC)
Swords & Soldiers: side-scrolling RTS (Switch/PS3/Wii/PC/Mac/Linux/iPhone/iPad/Android)
Proun: abstract racing game (PC)
Cello Fortress: mixing game and live cello performance
The Ageless Gate: cello album
User avatar
holocronweaver
Google Summer of Code Student
Google Summer of Code Student
Posts: 273
Joined: Mon Oct 29, 2012 8:52 pm
Location: Princeton, NJ
x 47

Re: The state of Ogre's documentation

Post by holocronweaver »

For my part, I plan to update the documentation and tutorials for every aspect of Ogre that I touch. I think if all the developers commit to this, we could have the documentation shaped up in a matter of months.

By the by, I went through and updated the beginner tutorials as I went through them, but will be going through them again at the end of my GSoC to support the GL3+ render system. This will involve updating the tutorial framework to use shaders, probably via RTSS.
User avatar
masterfalcon
OGRE Team Member
OGRE Team Member
Posts: 4270
Joined: Sun Feb 25, 2007 4:56 am
Location: Bloomington, MN
x 126
Contact:

Re: The state of Ogre's documentation

Post by masterfalcon »

Those are great points that absolutely need to be addressed. I would file bugs/feature requests on them.
Oogst
OGRE Expert User
OGRE Expert User
Posts: 1067
Joined: Mon Mar 29, 2004 8:49 pm
Location: the Netherlands
x 43
Contact:

Re: The state of Ogre's documentation

Post by Oogst »

masterfalcon wrote:Those are great points that absolutely need to be addressed. I would file bugs/feature requests on them.
Some of those are really bugs, but the last three are much bigger, general tasks. Should I add those to the bug-database as well, or is that not the right place for them?
My dev blog
Awesomenauts: platforming MOBA (PC/Mac/Linux/XBox360/X1/PS3/PS4)
Blightbound: coop online dungeon crawler (PC)
Swords & Soldiers: side-scrolling RTS (Switch/PS3/Wii/PC/Mac/Linux/iPhone/iPad/Android)
Proun: abstract racing game (PC)
Cello Fortress: mixing game and live cello performance
The Ageless Gate: cello album
User avatar
masterfalcon
OGRE Team Member
OGRE Team Member
Posts: 4270
Joined: Sun Feb 25, 2007 4:56 am
Location: Bloomington, MN
x 126
Contact:

Re: The state of Ogre's documentation

Post by masterfalcon »

Yeah, I think they'd qualify as either feature requests, improvements or paper cuts.
User avatar
Klaim
Old One
Posts: 2565
Joined: Sun Sep 11, 2005 1:04 am
Location: Paris, France
x 56
Contact:

Re: The state of Ogre's documentation

Post by Klaim »

Would there be a way to tag wiki pages with Ogre versions? What I mean is that:

- for readers, having a clear and visible way to identify for which versions the page is considered valid gives a lot of context information;
- for developers it's easier to spot pages which could be easily upgraded, pages which would be hard or should not (don't add tags or rewrite);

I'm thinking about this because I've seen other communities do this to help with documentation.
User avatar
spacegaier
OGRE Team Member
OGRE Team Member
Posts: 4304
Joined: Mon Feb 04, 2008 2:02 pm
Location: Germany
x 135
Contact:

Re: The state of Ogre's documentation

Post by spacegaier »

Some quick comments:
1. Manual is still on 1.8 since that is still the official version (not for long anymore!)
2. The tutorials in the wiki are nothing official, so we cannot guarantee anything there ;) ...in fact for the whole wiki.
3. Feel free to add it to the Porting Notes.

In general: Feel free to chip in wherever you can. I think I speak for the whole team, if I say that we welcome of course any support we can get on that matter!
Ogre Admin [Admin, Dev, PR, Finance, Wiki, etc.] | BasicOgreFramework | AdvancedOgreFramework
Don't know what to do in your spare time? Help the Ogre wiki grow! Or squash a bug...
User avatar
Wolfmanfx
OGRE Team Member
OGRE Team Member
Posts: 1525
Joined: Fri Feb 03, 2006 10:37 pm
Location: Austria - Leoben
x 99
Contact:

Re: The state of Ogre's documentation

Post by Wolfmanfx »

I totally agree with all your points except for the wiki which is really a community thing but the main docs need really a upgrade.
Oogst
OGRE Expert User
OGRE Expert User
Posts: 1067
Joined: Mon Mar 29, 2004 8:49 pm
Location: the Netherlands
x 43
Contact:

Re: The state of Ogre's documentation

Post by Oogst »

I of course understand that I shouldn't just complain and make some fixes myself as well, especially since the Wiki is public. :)

However, the part I really disagree with is that you talk about the Wiki as if it is less important for the core since it is a community thing. Keep in mind that for new Ogre users, the Wiki is their most important point of information, since all the tutorials are there. Even for more experienced users like me: the API and manual don't explain the exact combination of functions needed for more complex things, like editing a mesh from code. As far as I know, the Wiki is the only place where things like that are explained, so I think the Wiki is extremely important to the core of Ogre.
My dev blog
Awesomenauts: platforming MOBA (PC/Mac/Linux/XBox360/X1/PS3/PS4)
Blightbound: coop online dungeon crawler (PC)
Swords & Soldiers: side-scrolling RTS (Switch/PS3/Wii/PC/Mac/Linux/iPhone/iPad/Android)
Proun: abstract racing game (PC)
Cello Fortress: mixing game and live cello performance
The Ageless Gate: cello album
User avatar
masterfalcon
OGRE Team Member
OGRE Team Member
Posts: 4270
Joined: Sun Feb 25, 2007 4:56 am
Location: Bloomington, MN
x 126
Contact:

Re: The state of Ogre's documentation

Post by masterfalcon »

You're right, i've been thinking for a while that we may need to take a break and really work on the docs. Pulling from the wiki would be an important part of that.
User avatar
Wolfmanfx
OGRE Team Member
OGRE Team Member
Posts: 1525
Joined: Fri Feb 03, 2006 10:37 pm
Location: Austria - Leoben
x 99
Contact:

Re: The state of Ogre's documentation

Post by Wolfmanfx »

hehe i did not meant its less important but we do not have the man power to keep the wiki uptodate - so infact the community is important to keep up with the wiki.
PhilipLB
Google Summer of Code Student
Google Summer of Code Student
Posts: 550
Joined: Thu Jun 04, 2009 5:07 pm
Location: Berlin
x 108

Re: The state of Ogre's documentation

Post by PhilipLB »

I'd vote for some parts of the wiki being updated by the team. For example everything needed for a nice start like the tutorials. They are crucial IMHO. :)
Not every shader of course.

I feel responsible for the volume component pages. :)
Last edited by PhilipLB on Wed Jul 24, 2013 10:45 pm, edited 2 times in total.
Google Summer of Code 2012 Student
Topic: "Volume Rendering with LOD aimed at terrain"
Project links: Project thread, WIKI page, Code fork for the project
Mentor: Mattan Furst


Volume GFX, accepting donations.
User avatar
holocronweaver
Google Summer of Code Student
Google Summer of Code Student
Posts: 273
Joined: Mon Oct 29, 2012 8:52 pm
Location: Princeton, NJ
x 47

Re: The state of Ogre's documentation

Post by holocronweaver »

None of the components (RTSS, paging, terrain, volume) have official documentation, only what is on the wiki. They are close to undocumented since none have a good introductory tutorial. I think the components should be a major focus of updating the main documentation and could perhaps be included as a supplementary or addendum. The components are generally of good quality - it would be a shame for them to languish due to poor documentation.

I have already begun writing documentation for the Paging component which I plan to finish when GSoC is over.
Transporter
Minaton
Posts: 933
Joined: Mon Mar 05, 2012 11:37 am
Location: Germany
x 110

Re: The state of Ogre's documentation

Post by Transporter »

It could be useful starting with update the doc in 1.9 source branch now, because it is a lot of work. The basic tutorials (Setting Up an Application) should be a part of the documentation for a quick start. Also, there should be example codes in the manual. In OgreProcedural's doc, I try to give small examples for each class (example: http://docs.ogreprocedural.org/classPro ... ml#details). I agree to holocronweaver. I would appreciate to have a chapter for each component in the manual - with a code example.
al2950
OGRE Expert User
OGRE Expert User
Posts: 1227
Joined: Thu Dec 11, 2008 7:56 pm
Location: Bristol, UK
x 157

Re: The state of Ogre's documentation

Post by al2950 »

holocronweaver wrote:None of the components (RTSS, paging, terrain, volume) have official documentation, only what is on the wiki. They are close to undocumented since none have a good introductory tutorial. I think the components should be a major focus of updating the main documentation and could perhaps be included as a supplementary or addendum. The components are generally of good quality - it would be a shame for them to languish due to poor documentation.

I have already begun writing documentation for the Paging component which I plan to finish when GSoC is over.
I started to create documentation for the components, I created a structure and created some RTSS tutorials but I have not uploaded them yet. If you are going to add component documentation then I suggest you use the basic strucutre I started: http://www.ogre3d.org/tikiwiki/tiki-ind ... =Tutorials

I created it within the tutorials structure but have not put a link on the tutorials page as it contain no content!
Oogst
OGRE Expert User
OGRE Expert User
Posts: 1067
Joined: Mon Mar 29, 2004 8:49 pm
Location: the Netherlands
x 43
Contact:

Re: The state of Ogre's documentation

Post by Oogst »

I have added my issues to the JIRA, and added "plugins_d.cfg" to the porting notes.

I would also like to stress how incredibly important this whole topic is. The current plan for Ogre has all this talk about performance improvements, but none of that matters if Ogre is too difficult to use. I am quite an experienced programmer myself: I have been using Ogre for over 9 years now for my hobby projects, and as lead programmer of my game company (with my own engine) I have released successful games on a bunch of different consoles. Yet working with Ogre, so far I have not been able to get DX11 and integrated depth shadows to work with my hobby game. I simply cannot find the documentation that explains it.

If I can work with console devkits but not with Ogre, I thing Ogre has a serious problem. I love Ogre, so I'd like to help improve this, but I also want to stress again that I think this is a BIG problem for Ogre! Much more important than improving performance or adding features!
My dev blog
Awesomenauts: platforming MOBA (PC/Mac/Linux/XBox360/X1/PS3/PS4)
Blightbound: coop online dungeon crawler (PC)
Swords & Soldiers: side-scrolling RTS (Switch/PS3/Wii/PC/Mac/Linux/iPhone/iPad/Android)
Proun: abstract racing game (PC)
Cello Fortress: mixing game and live cello performance
The Ageless Gate: cello album
User avatar
masterfalcon
OGRE Team Member
OGRE Team Member
Posts: 4270
Joined: Sun Feb 25, 2007 4:56 am
Location: Bloomington, MN
x 126
Contact:

Re: The state of Ogre's documentation

Post by masterfalcon »

I agree 100%. It is extremely important and though there is a lot of various bits of documentation many are out of date, inaccurate, incomplete or there are just topics missing. I'm working on a plan to improve this now.
User avatar
only_a_ptr
Halfling
Posts: 62
Joined: Sun Apr 26, 2009 8:43 pm
x 2

Re: The state of Ogre's documentation

Post by only_a_ptr »

spacegaier wrote:1. Manual is still on 1.8 since that is still the official version (not for long anymore!)
IMHO there should be 2 versions of the manual available: ''stable" and "development". Since the unstable version (currently 1.9RC1) is out for testing by users, it would make sense to equip it with it's own manual, so that users get a kick start.
Oogst wrote:Some of the things I noticed...:
-The samples have so many options and thingies that it is really difficult to see in their source code how to actually achieve some effect. The samples are fine for showing off Ogre, but pretty bad as examples of how to actually use Ogre. I think there should be a large set of mini-applications that do only one thing in the absolute minimal way, to make it much easier to learn how to do things from that.
Umm, I'm not getting this impression. I haven't looked on every sample, but those I saw were a single header file with not much code in it. For example, the "bump mapping" sample helped me a lot, and it's really short and simple.
Which examples did you mean exactly?
Rigs of Rods is alive and kicking!
Oogst
OGRE Expert User
OGRE Expert User
Posts: 1067
Joined: Mon Mar 29, 2004 8:49 pm
Location: the Netherlands
x 43
Contact:

Re: The state of Ogre's documentation

Post by Oogst »

An00biS wrote:
spacegaier wrote:1. Manual is still on 1.8 since that is still the official version (not for long anymore!)
IMHO there should be 2 versions of the manual available: ''stable" and "development". Since the unstable version (currently 1.9RC1) is out for testing by users, it would make sense to equip it with it's own manual, so that users get a kick start.
On the website there is indeed the question which Manual to show, but the Manual is also simply in the SDK package. I suppose that comes from the Mercurial repository, so that automatically goes right for the downloadable packages if you just edit it in the repository, right?
Oogst wrote:Umm, I'm not getting this impression. I haven't looked on every sample, but those I saw were a single header file with not much code in it. For example, the "bump mapping" sample helped me a lot, and it's really short and simple.
Which examples did you mean exactly?
I had this problem with the shadows example.
My dev blog
Awesomenauts: platforming MOBA (PC/Mac/Linux/XBox360/X1/PS3/PS4)
Blightbound: coop online dungeon crawler (PC)
Swords & Soldiers: side-scrolling RTS (Switch/PS3/Wii/PC/Mac/Linux/iPhone/iPad/Android)
Proun: abstract racing game (PC)
Cello Fortress: mixing game and live cello performance
The Ageless Gate: cello album
User avatar
only_a_ptr
Halfling
Posts: 62
Joined: Sun Apr 26, 2009 8:43 pm
x 2

Re: The state of Ogre's documentation

Post by only_a_ptr »

Oogst wrote:
An00biS wrote:
spacegaier wrote:1. Manual is still on 1.8 since that is still the official version (not for long anymore!)
IMHO there should be 2 versions of the manual available: ''stable" and "development". Since the unstable version (currently 1.9RC1) is out for testing by users, it would make sense to equip it with it's own manual, so that users get a kick start.
On the website there is indeed the question which Manual to show, but the Manual is also simply in the SDK package. I suppose that comes from the Mercurial repository, so that automatically goes right for the downloadable packages if you just edit it in the repository, right?
Yup, it seems to work that way, mercurial and SDK manual is the same. The problem is it's just 1.8 stable :|
In fact, it's a bit older than the online version, which is dated August 20, 2012. The SDK/mercurial version is dated May, 26 2012 :roll:

EDIT: On a related note, mercurial/SDK directory "/Docs/vbo-update" contains a document titled "Geometry Changes In OGRE 0.12" :lol:
Rigs of Rods is alive and kicking!
Oogst
OGRE Expert User
OGRE Expert User
Posts: 1067
Joined: Mon Mar 29, 2004 8:49 pm
Location: the Netherlands
x 43
Contact:

Re: The state of Ogre's documentation

Post by Oogst »

Then the only problem is simply that no one updated it, right?
My dev blog
Awesomenauts: platforming MOBA (PC/Mac/Linux/XBox360/X1/PS3/PS4)
Blightbound: coop online dungeon crawler (PC)
Swords & Soldiers: side-scrolling RTS (Switch/PS3/Wii/PC/Mac/Linux/iPhone/iPad/Android)
Proun: abstract racing game (PC)
Cello Fortress: mixing game and live cello performance
The Ageless Gate: cello album
User avatar
masterfalcon
OGRE Team Member
OGRE Team Member
Posts: 4270
Joined: Sun Feb 25, 2007 4:56 am
Location: Bloomington, MN
x 126
Contact:

Re: The state of Ogre's documentation

Post by masterfalcon »

Yeah, we made a decision a while back to not update the version in the source repo because it would just keep bloating the repo. We should remove those files because they are out of date.
Transporter
Minaton
Posts: 933
Joined: Mon Mar 05, 2012 11:37 am
Location: Germany
x 110

Re: The state of Ogre's documentation

Post by Transporter »

masterfalcon wrote:Yeah, we made a decision a while back to not update the version in the source repo because it would just keep bloating the repo. We should remove those files because they are out of date.
What about creating a seperate repository for the documentation? To keep down the repository size it's possible to delete and recreate the repository after each release.
User avatar
Klaim
Old One
Posts: 2565
Joined: Sun Sep 11, 2005 1:04 am
Location: Paris, France
x 56
Contact:

Re: The state of Ogre's documentation

Post by Klaim »

Transporter wrote:
masterfalcon wrote:Yeah, we made a decision a while back to not update the version in the source repo because it would just keep bloating the repo. We should remove those files because they are out of date.
What about creating a seperate repository for the documentation? To keep down the repository size it's possible to delete and recreate the repository after each release.

I also agree on that. I think the generated documentation is big enough that it can be considered a separate sub-project. It could use it's own repository.
That being said, an easy way to do this without breaking compatibility with previous state of files in repository would be to use subrepos (ogre repo->specific ogre doc repo changeset). Unfortunately it's almost never the best choice, I have several cases where having separate repos with just a check in CMake to make sure they are in compatible version on compilation was far better. Another issue is that it separate code from documentation that comes from that code.

Thinking more about that, personally if I find the repository big, I would have trimmed it and kept an archive somewhere to keep available the changes before the trim.
User avatar
masterfalcon
OGRE Team Member
OGRE Team Member
Posts: 4270
Joined: Sun Feb 25, 2007 4:56 am
Location: Bloomington, MN
x 126
Contact:

Re: The state of Ogre's documentation

Post by masterfalcon »

Here is my rough outline for a plan. It has 3 main phases.

Phase 1: Update existing docs. Correct inaccuracies.

Phase 2: Solicit feedback from the community on what specifically they would like to see and what areas are currently lacking.

Phase 3: New Documentation
  • - Components
    • - RTSS
      • - Explain how to use
        - How to extend
    • - Getting started
      • - Each platform
        - Explanation of .cfg files
    - Plugins
    - Links to key tutorials
    - Update tutorials
    - Examples
I am also thinking that for Phase 3 it would be a good idea to enlist some individuals to help write some of documentation. What do you guys think?
Post Reply