<http://www.docbook.org/>
The advantage of DocBook is that we can simultaneously create HTML and PDF from the same source documents. We can also easily create a single document with all of our developer documentation, as well as split things out into smaller packages. Finally, there's an example of an entire O'Reilly book that was produced with DocBook and for which the sources and build instructions are available as open source:
<http://svnbook.red-bean.com/>
My thought is that we could simply adopt this format and basically generate our own O'Reilly book for Hackystat. :-)
The disadvantage of DocBook is that is seems to have an extremely steep learning curve. I would imagine I will invest weeks in the process of putting together the toolset, writing the ant tasks, and just generally figuring out how everything should work. On the other hand, once everything is together, we could do things like have each module (hackyKernel, hackyTelemetry, etc.) supply its own DocBook-compatible XML file of high-level documentation that could be added into the other documentation to provide a summary of the modules that are available and what they do. We could have an XSLT transformation of the command XML definition files into DocBook XML, to automatically generate a reference of all the commands available in the system.
So, I'm looking for opinions here. Does this seem like a good direction to go? Are there other technologies for documentation that we should be thinking about instead?
Cheers, Philip
