Last week I switched our documentation system to use Jekyll[1]. Before the switch we used Docter to generate the Web site from Textile documents and HAML templates. Jekyll replaces that with Textile documents and Liquid templates.
The main reason for the switch: I have a strong preference to maintain as little code as possible, and since I was the one maintaining Docter, I was also always on the lookup to replace it with other people's code. Jekyll was built for Github page[2], so it's bound to get more care and attention. It's also, for those of you using Github pages, one less tool to learn. The only change to the Textile files was the title/layout header that Jekyll requires and using different tags to markup code snippets. Syntax highlighting is now done by the more powerful Pygments, a Python app. PDF generation still done by PrinceXML. If you like the idea of using Textile to generate HTML and PDF, there are a few more tips on my blog[3]. Another change, we're not using the Hanna template for the API documentation (RDocs). If you look at the left-side navigation pane[4], you'll notice a search bar that does as-you-type method search across all classes/modules. While on the subject of documentation, the Web site (and PDF) have two sections called Recipes and Troubleshooting. The Wiki has two sections called "Buildr How Tos" and "Common Problems and Solutions". I'd like to consolidate both. The Wiki is much easier to edit than the Web site, so my preference right now is to consolidate these duplicates and move them over to the Wiki, with a link from the Web site navigation. Where it says Recipes right now it will say HowTo and link to the Wiki instead of another page on the site. The downside is that these two pages will no longer be part of the PDF. Assaf [1] http://github.com/mojombo/jekyll/ [2] http://pages.github.com/ [3] http://blog.labnotes.org/2009/03/14/buildr-how-we-generate-the-documentation-web-site-and-pdf/ [4] http://buildr.apache.org/rdoc/
