Forums / Cotonti / Documentation / Tutorial section

GHengeveld
#26504 2010-10-05 04:07
Well, I think the whole documentation structure needs a re-thinking. To me, it makes no sense having languages as root directories. Multiple languages is good, but it's better to have everything in English, with a list of alternative languages for an article if they are available.

Something that bothers me with the current multi-language setup is that I have no idea if there is some information available in Russian for example, which is not available in English. I think documentation should be in English by default, with optional translations for other languages. For technical documentation its even worse because it quickly gets outdated, so its best to keep this all in English.

One thing that I know for sure is that Cotonti can be so much more popular if we'd just have some decent documentation. Preferably the documentation should be concise but complete, and presented in a way that is coherent and simple. Having to click though many categories of pages is not what I think of when I say simple. We should take example of other well-known open source projects in terms of documentation. For example, the Django documentation is one of the best examples around, and the Pylons docs is very good also. You'll notice the difference very quickly: they dont have pages stuffed in categories, they actually wrote it like a physical manual, and the index is, well, the index. Everything accessible from one page.

This topic is locked, new posts are not allowed.