Ogre3D's Documentation Problem

So Ogre3D is a great library/framework/engine. It's Open Source, fairly easy to extend, is used by a few prominent games, one of the only stripped down and scalable rendering engines written in C++ and is ridiculously cross platform. As far as I can tell, it's failry easy to work with once you get going. Ogre3D is absolutely atrocious to get going, though.

The few times I've tried to get it working, the more I've realized that the documentation is written for someone who already knows quite a bit about Ogre, not for a complete beginner to it. A great example is trying to get a basic application set up from the SDK or source.

This adventure began with trying to set up Ogre3D on my mac. Yeah, it didn't work. I tried multiple times to get either the SDK or the source to build, and even with everything set up perfectly, it just wouldn't. Often, it was the tutorials that were out of date, missing crucial steps, or not having clear enough documentation. I abandoned it and switched back to my windows machine.

I've set it up on Windows before, even built from source, so I set out to do that again, having forgotten all the errors I had to work through to get it going again.

The first thing is, when you go to the main tutorial page, you are greeted with a whole bunch of tutorials, and a specific set that seems to be the right set: Basic Tutorials. You click on the first tutorial, and you're told that you need to go complete a prerequisite: setting up an application and setting up the Ogre wiki framework. So you click on setting up an application.

That one is how you set up the application using visual studio, but before you do that, you have to install ogre. So you click on that link to get to the real first one. After working through that first one, then working through the other first one, you run into a bunch of errors with no real explanation.

Among others: The include paths have changed, but neither the files nor the tutorials have been updated to include the new changes. The resource paths have been shuffled around, as well, and the resources.cfg file either was never updated, or the tutorial was never updated to fix it. You get cryptic errors about the fixed function pipeline or missing files, without any indication where the actual error is. Also, if you try to run it with the D3D11 renderer, it won't work. There's no explanation as to why(the tutorial application uses primarily fixed function shaders is the reason).

http://www.ogre3d.org/forums/viewtopic.php?f=1&t=78166 - missing includes and library files? Try this one. Also, add "$(OGRE_HOME)\include\Overlay;" to your include directories (sans quotes).
http://www.ogre3d.org/forums/viewtopic.php?f=2&t=78338 - missing resource files? Try this.
http://www.ogre3d.org/forums/viewtopic.php?f=2&t=81280 - wondering why it won't work in D3D11? Here's a thread that explains it.

So finally, you follow the little bread crumbs, type every little issue into Google, and finally, you get it working. What are you greeted with? This:

Now, it appears to be working, but it bothers me that there's no indication from the "setting up an application" that says what you're supposed to see. There's a suggestion to go set up precompiled headers to optimize your build time (something you really don't need to do at this stage), but not what you're actually supposed to see.

Getting it working is a pain, and it shouldn't be. Looking around at the tutorials, there's three versions of everything. The SDK is at version 1.9 stable and 1.10 development. The manual is at 1.9. Most of the tutorials are 1.7. Why aren't they all updated when the new version comes out? If you want people to use your libraries, then make sure they're well documented. Make sure that the basic stuff to get them going is friendly to new users.

I don't know what the process or infrastructure would be to improve the documentation and getting started tutorials, but I intend to find out. There is no reason for it to be this disjointed. Hopefully as I get this Independent Study going, I can write some tutorials here on the blog, and can get the documentation for this great library/framework/engine improved.