I find myself this Saturday in the possession of a half-full pitcher of mojito. This is something of a problem, given that I need that very pitcher to make mojitos for tomorrow's Sunday barbecue. So I have been doing my best this afternoon to rectify the problem. I only bring this up so that if this post seems less coherent than usual, it's because of the Demon Rum. In vino veritas, and all that.
So. In the course of my job, I need to produce documentation that falls into these basic types:
- API documentation: a terse reference for the classes and methods available for a particular C++/Java/PHP/whatever library.
- Man pages: a terse reference for the commands and options available for a particular command-line tool.
- User guides: conceptual information and examples, written around the relevant API documentation and man pages.
And I need to produce said documentation in the following formats:
- HTML: the primary format for modern documentation. At my very first job, we produced our documentation as very nice perfect-bound 7"x9" manuals using Framemaker. That era is long gone.
- PDF: in case someone needs to print the documentation.
- troff: man page format, suitable for installing into
/usr/share/man/ or wherever man pages go. To be honest, I'm somewhat confused about the difference between troff, nroff, and other *off variations. But I suppose I shouldn't worry my pretty little tech writer head over such things.
For engineering documentation, I don't think these types and formats are all that shocking. There are thousands of writers and engineers who are faced with the same problem every day. And yet there is no documentation technology that can handle all of these documentation types and output formats seamlessly. None.
AuthorIT, Framemaker + Webworks, and other mid-range tech writing tools can at least produce output HTML and PDF. All of these tools are Windows-only. All use a proprietary binary format. None handles man pages and source code-generated API documentation. (We won't even mention Microsoft Word, which still hasn't figured out how to do ordered lists consistently, or handle documents longer than 100 pages.)
The only toolchain I'm aware of that even comes close is Docbook. It's text/xml, so it plays nicely with UNIX. It doesn't require an expensive client to edit. It can produce output in myriad formats, including HTML, PDF, and man pages. It's open source. It's modular (with XInclude). It is the only documentation tool chain that even approaches the holy grail of user guides, API guides, and man pages.
Except... There's no such thing as "out-of-the-box" Docbook: you need to pick your editor, XSLT processor, FO processor, and template customizations, and there is very little guidance on how to do this.
Except... the default HTML output looks like something out of 1993. Basically, the output is nicely-marked up semantic HTML with no CSS whatsoever. Which is fine, except that this means you're going to have to sink some time into making the HTML look pretty.
Except... PDF output is really buggy, mostly because the major open source FO processor is still in beta status. Not that I blame them -- XSL-FO is hard, and typesetting in general is really hard. But the alternative is to buy a commercial FO processor for $4000/CPU... grrrr...
Except... in general, source code documentation generators do not integrate with Docbook. For Java code, there's a Javadoc doclet that produces Docbook (yay!). For PHP code, phpdocumentor can generate Docbook natively (yay again!) But for C++, Perl, Python, and other languages, you're screwed.
Why oh why does documentation software suck?