Thoughts on Documentation
My general thought process is that if I see something that I think I can be improved, just don't complain about it, but offer a suggestion.
So my thoughts turned to the documentation that's available for JNode. What could we do to improve the documentation, and what do I mean when I say improve it. Documentation is difficult, and can be boring if you don't have the mindset for it. It's also extremely important for new and old users to have a robust level of documentation to support the project.
One of the obvious solutions is a wiki, however wiki's require monitoring and administration and servers. Another solution, which JNode is currently doing, is centralizing the documentation on a CMS but limiting the rights of the people who can modify it. This can work pretty well but can suffer for the same reason that wiki's do which is the lack of man power in a slow moving, large project.
My recommendation is to push the core documentation into the source code, as a project in it's own right.
Which provides the following benefits
- Documentation is now available offline
- There is a history of the documentation
- "patches" to the documentation can be made by any user, and in the case of github a pull request can be made.
- independent of the lifecycle of the website
The question would be, how would you put the documentation there and in what format.
- Documentation needs to be human readable, and editable
- Interface into the documentation should be via a browser to provide a professional look and feel
- Documentation should try to avoid html
I put a smiley at the end of the list since I just listed two requirements that would seem to indicate web pages, the problem with web pages is that they really aren't readable and a pain to upkeep and write documentation in without an editor.