Page 1 of 1

[GSoD 2019] Idea Discussion

Posted: Wed Apr 03, 2019 11:11 am
by paroj
One of the major complaints in this years survey, was the lack of up-to-data documentation: ... wanalytics

TOPIC # 1: Collect & update WIKI based tutorials
One part of the issue are our old wiki based tutorials. Those currently target Ogre <= 1.9 and do not use our simplified ApplicationContext class and generally use old practices.

Any documentation on the wiki also tends to fall out of date quickly. Therefore we introduced an unified documentation approach with Ogre 1.10, where tutorials are stored along the code in the git repository.
The tutorials are written in diffable & reviewable markdown, while referencing actual code that can be compile tested through Doxygen.

Unfortunately, so far we had only one external contributor porting content from the wiki to the new infrastructure:

An applicant should be familiar with C++ and work his way through the basic ported tutorials. Based on this, he should take a look at the remaining Wiki tutorials and port them to the new system. See the this pull request for reference.

TOPIC #2: Re-target existing documentation
Many parts of the OGRE user manual written from the implementors point-of-view instead of taking the user perspective. This makes it hard for potential users to derive the useful information.
An instance of this is the RTSS documentation. The according user complaint.

TOPIC #3: Write in-depth tutorials
The second documentation issue is the lack of tutorials on in-depth topics. While we have demos for advanced effects like
  • Bump Mapping
  • Cube Mapping
  • Volumetric Terrain
  • Particle System
  • Compositors
  • Particles
generally those only show code. It is desirable to have textual explanation as well.

The applicant should either be already familiar with the aforementioned Ogre concepts or be able to gather the necessary information from the Wiki and the API docs to write according tutorials.

Re: [GSoD 2019] Idea Discussion

Posted: Wed Jul 31, 2019 12:06 am
by lonewolff
Yeah, documentation is my biggest gripe.

Ogre 3D was the first graphics engine I ever used (around the 1.2 days). I hadn't even coded in C++ before at that stage, so it was quite the learning curve. But the documentation was pretty spot on. That was with a very thriving community though, which has sadly died right off.

I have tried the newer versions in recent years but don't get very far, especially with 2.x. And asking questions on the forum is a non event, taking days or weeks to get a response (if at all).

I'm not sure what the answer is. Maybe if focus was pulled from development and back on to documentation, things may turn around. I understand this would be a huge collaborative effort.

As someone who was a fairly advanced user of 1.2 through to about 1.7, I just have no idea where to even start with 2.x. I'd love to give it a crack once again, but just can't with documentation in its current state. Not saying I don't want to, just no idea how to.

Ogre 3D is by far the best and friendliest community I have ever been a part of. I'd love to see it return to the super power that it once was and am happy to assist in any way I can.

Re: [GSoD 2019] Idea Discussion

Posted: Wed Jul 31, 2019 12:25 am
by lonewolff
I just had a quick peek at the 2.x tutorials again. But my fears were confirmed.



And no SDK on the downloads page for version 2. Everything needs to be built from scratch. Which is a huge turn off for people who just want to get in and have a go.

Ogre is not an accessible option anymore. :(

Re: [GSoD 2019] Idea Discussion

Posted: Wed Jul 31, 2019 6:23 pm
by paroj
note that version 1 and version 2 are developed in parallel. You can almost think of Ogre1 and Ogre2 as separate projects. See viewtopic.php?f=4&t=94758 for some background.

One of the reasons for me to keep developing Ogre1 is indeed that all the documentation is already out there, which by far reduces the maintenance burden. I only have to clarify thinks here and there instead of writing all from scratch.

Re: [GSoD 2019] Idea Discussion

Posted: Thu Aug 01, 2019 2:20 am
by lonewolff
Yeah, I treat them as separate entities also as they are very different.

But there doesn't seem to be any starting point for Ogre 2. Can't find any information on how it is used, despite 2.x having been in the wild for many years now.

And Ogre 1 seemed to change a fair bit around the 1.8 era with panels and a bunch of other implementations changing around that time. But at least there is a bit of information around for this if you dig hard enough.