Documentation offensive!!!

[Skaldarnar]

Hey guys

I think its time for a documentation offensive! I want to cover two main areas with that:

1. user documentation - give users a good documentation at hand. Nobody is going to search through the forum to get to know what mods are, how exactly these miniions work and so on. I think the wiki would be a good place to collect all this information, provide tutorials and stuff. As always, pictures and videos can help a lot!
2. developer documentation - I think that's the easier part. Most of us follow the discussions in relevant threads and attend some interesting convos on the IRC. But nevertheless, haning around on the chat there are so many questions that are asked the 3rd time - we have to write down the answer somewhere! The important points here are

• Keep incubator header up to date - if you've reached a goal (or even a part of it) you may give a hint in the first thread, something like a TODO list. That gives new contributor the chance to get an easy overview of what is working and what not. Or rewrite the summary from time to time as things change.
• Create wiki pages as well - the wiki pages are useful for developers, too. You can provide useful information on your system, how you solved problems or just give examples on how to use your part of code....
• at least write good javadoc - this part should be self explanatory. The more descriptive the method/variable/class names, the easier to understand

 

[Cervator]

Hehe, at first seeing the subject line I thought somebody had found something offensive in our documentation and wanted to complain

Yes, more docs are good docs, especially if possible to extract automatically from one place to another! I'd love to see the mod.txt or code in modules expanded to where we could automatically pull some general usage information to post in the wiki, that way at least there's one section that won't go out of date vs. code

Checkstyle will complain about missing Javadoc comments, if we can do a major campaign to bring down warnings at the tail-end of the multiplayer / restructuring work we might be able to then start keeping up better. Would be good to lay down a great foundation in a doc/minor fix focus period.