I’ve been spinning my wheels on the concept of scalable, portable documentation and how to get that into opensource and internal projects that I work on.  It is no wonder so many opensource products lack good documentation, not only is it taxing to do to, but the tools for generating decent documentation either suck or are too costly (such as Adobe’s Framemaker or oxygen XML).

Wiki’s help, but writing docs in a specific wiki format is not exactly portable.  HTML is sort of portable, especially XHTML to which you could apply XLST against it to transform it into whatever XML format.

The docbook format has value, especially version 5 and the fact that O’Reilly, PHP, Fedora, and other large groups/company’s use it. The sting is that the tools still seem lacking and most are in Java.  My only concern is that it seems that Java does not seem to be progressing and Sun/Oracle is only servicing the byte code layer for things like Scala, JRuby, etc as a friend of mine and fellow developer Ashish Tonse pointed out.   I’m not about to cry wolf and say “Java is dead” or say its evil, when it has many stable, mature frameworks and libraries and probably better build processes and continuous integration like Maven and Hudson. Java is just an all around wonder for the opensource community in general.  I just wonder about the long term and think that things like Mono/C# would be the way to go, as it will allow for things like Iron Python and Iron Ruby which are widely used dynamic languages to be tied into it.

I’ve used tools like sandcastle,PHPDoc, and Rdoc to generate documentation. Each have their own strengths, but mostly they have weaknesses at this point.  The ability to easily extend, change the output, or search ability of the documentation generated is definitely weak in all documentation tools that are out there.   I’m wondering what if the community developed some kind of docbook like system with easy templates to modify whether XSLT or T4, or even Ruby with Rails like templates,whatever flavor you are interested in.

For now, I guess i’m stickying to putting html tags into a wiki on github, with hopes of using the github api and parsing the XHTML later into a different format.