I often need to write technical documentation to describe the function of a script that I wrote (usually something in perl or powershell) or for a tool that we’re using. Over the years, I’ve written that in plain html on a Google Site, Word documents, Google Docs, and once in a while, Markdown. Recently, through a mention on HackerNews, I came across a new tool, for me, that makes whipping up technical documentation a lot easier.
AsciiDoc is a MarkDown-like format that takes very easy to write plain text data and formats it on demand into HTML, PDF, or some other desired format. The output looks terrific and the formatting is properly separated from getting all of the content correct. I particularly like how well syntax highlighted source code is integrated. I find the default styling perfectly acceptable, but some custom CSS will produce a pleasing-looking company specific document. What’s more, that styling will be perfectly reproduced across all of the documentation.
Even better, the system is maintainable. Because it’s a pure text format, it can all be checked into source control to manage revisions over time. Makes it real easy to tell when and what changed months later. When there are changes, a quick rebuild delivers a perfect document everytime in a variety of different formats without a lot of painful style and alignment adjustments.
Not sure yet about selling it at the office due to the ruby dependencies (and python for the pygments library), but I’ll absolutely be keeping it in my own toolbox.