Documentation is something that most developers fear/hate and some of us usually avoid it til the end of a project. And im not talking about, the more mandatory, javadoc. *Ahem*
However, open-config need a presentation sketch for readers (and potential contributors) to learn about the project, allowing them to form an immediate first impression.
I dont want (and cant) document everything before even getting started. But the plan is to have a clear and concise mission statement, brief list of planned features, the most fundamental development guidelines and principles, high level design and something about project governance. I will do this before start coding, because I do not want to worry about it (too much) when im “in the zone” .
I recently found out about docbook, which btw is highly praised by the open source community, im actually a bit surprised i did not stumble on it in earlier. Docbook allow writing content decoupled from the presentation-view, using XML files. These XML files can then be transformed into navigable HTML pages, PDF, XHTML, man pages etc. Sweet! The syntax is a bit complex but since it is based on regular XML i can probably use an editor, with autocompletion and nice GUI, to help me out.
Docbook can also be easily integrated into maven (well, i had to spend a few hours on it) using docbkx. This is important because documentation must be tracked by strict version control, a wiki is far too weak in this regard. Having documentation in the same GitHub repository as code makes it easy to update since commits can include documentation changes and thus remain up-to-date with latest development. Documentation can also be branched along with code releases.
When changes are made, simply upload the latest maven-generated HTML and PDF to the project website.
The most important project artifacts can now stay in (almost) perfect sync, no matter what medium readers wish to view it on. No more excuses for doing late documentation… yikes!