Documentation initiative

[mrmclovin]

I'd like to start a discussion regarding Ogre's documentation. This is a spin-off from my other thread:
viewtopic.php?f=25&t=95559 which didn't received the feedback I was hoping for so I'm making a new attempt here.

I think that features, code quality, API stability etc. are the most important parts Ogre 2 project, followed by community & documentation right after. The current state of the docs are IMO good, but has room for more improvements.

Being a bit subjective, but the move of this project to Git and Github was, to me, a very wise decision. The project now has the best tools to grow, community-wise (disclaimer: I'm very git biased). Additionally, putting the manual & API reference into doxygen was also a very good move. Updating the documentation is a matter of creating PR. It will get reviewed by someone with knowledge to assure quality and correctness - once merged, it's there, in one place, version controlled. This is a quite straight forward workflow.

I don't want to write an essay so I shall get to my point of what I would like to change/see in this project:

* Establish guidelines of how one could contribute to the docs (how to add images etc.)
* Encourage others to contribute, even (especially) if it's a small addition or re-wording
* Making small doc-contributions is a great way to feel engaged
* Making small doc-contributions is a great way to be a part of the project
* Making small doc-contributions is a stepping stone to become more involved and knowledgeable - opening up for more advanced contributions

I have been tinkering a bit with the docs today and I'd like to kick-off this discussion by sharing the results which can be previewed at:

https://mimon.github.io/ogre-next/html/index.html

It has been generated automatically based on the master branch - using Github's Action feature which is something I think we should consider integrating in the official repo. It also features some style changes to resemblance common markdown pages. I'd like the docs to feel familiar and adopt common styles of today. The current official one feels old and outdated.

Regarding the manual, content-wise, I think It'd be good to:
* Rewrite the parts which are "this has changed since ogre 1.x" and reprashe it into a more "this is how you do it"
* Rewrite the parts that says "works in the same way as ogre 1.x" and replace it with actual content from the ogre 1.x docs

In summary, I think the current documentation is good, but a slightly spread out. So I think we should clean it up, automate the deploy of the official docs and make it easier for anyone to get started fixing/writing docs.

[dark_sylinc]

Autogenerating docs: Yes! If we get that to work it would be great!
It also makes small contributions easier, since they're immediately visible

Rewrite the parts which are "this has changed since ogre 1.x" and reprashe it into a more "this is how you do it"

For 2.2 and onwards (i.e. master branch) I agree.
For 2.1 branch, leave it as is (since we have users porting from 1.x)

Rewrite the parts that says "works in the same way as ogre 1.x" and replace it with actual content from the ogre 1.x docs

I agree (again, for 2.2+)

One more thing I can add: Our landing page for the documentation contains 1.10 stuff and no link to the actual API documentation.
This needs fixing.

[mrmclovin]

Autogenerating docs: Yes! If we get that to work it would be great!
It also makes small contributions easier, since they're immediately visible

Nice, I'll cook up something in a coming PR

For 2.2 and onwards (i.e. master branch) I agree.

Good, let me write a small guideline proposal regarding general documentation.

One more thing I can add: Our landing page for the documentation contains 1.10 stuff and no link to the actual API documentation.
This needs fixing.

Yes, I've noticed that there's an open issue on this. I can probably tackle that in a separate PR.