The state of Ruby on Rails documentation II: Return of the Manuals
Last time I blogged about the state of Ruby on Rails documentation. Those of you who have been around long enough probably remember manuals.rubyonrails.org. Back in the days, this website was very useful. But today, it’s horribly outdated. The first manual is “Upgrading to Rails 1.0″. I don’t think I need to say more.
In fact, it was not too long ago when that website was linked from rubyonrails.org. It appears they removed the link because it’s so old. But why hasn’t that website been updated?
- It’s a database-backed web application. Only a few people have write access to the website so the general public cannot contribute.
- The content management system is horribly out of date and hasn’t had a release since 2006.
Which is a shame. Some of the manuals on that site are really good, if only they’re more up to date.
Ever since I found out that the Ruby on Rails documentation on testing is horribly out of date, I’ve felt this irresistible urge to write documentation. In truth, I had been secretly contributing more documentation. And it was not without result. I’ve been working on converting some of the manuals to Asciidoc format while updating their content at the same time. Asciidoc is the documentation formatting tool used by Git. You write documentation in plain text files, and Asciidoc can convert it for you to HTML, Docbook, PDF, Unix man pages, etc. By saving the manuals in plain text files, they can be put on the Ruby on Rails source repository, so that everybody can contribute. Asciidoc is great - the Phusion Passenger manual is also written in it.
Unfortunately Asciidoc’s default HTML output layout isn’t good enough, and Asciidoc doesn’t allow you to specify a different layout. So I’ve spent my entire Saturday hacking together a new documentation formatting tool, based on Asciidoc: Mizuho. Mizuho accepts Asciidoc input files, and generates nicely formatted HTML. Multi-page HTML output is also supported! Furthermore, the HTML layout can be customized with ERB templates.
How does the result look like? Here are some previews:
- Securing Rails applications
- A Guide to Testing Rails Applications
- The Basics of Creating Rails Plugins (a new manual written recently)
These have been generated by Mizuho with the “manualsonrails” template.
I’ve committed the new Asciidoc-formatted manuals to the docrails repository, so you are likely to see a revival of manuals.rubyonrails.org. You can find the manuals source files under railties/doc/guides/.
I’ve spent some time updating “A Guide to Testing Rails Applications”, but it’s likely still out of date. If anyone spots outdated information, please contribute a patch. Thanks. 
beauty is fleeting (or why rails-doc isn’t the answer but something else might be) | omg blog!! lol!! said,
July 22, 2008 @ 4:57 am
[…] not anywhere near a total fix for the poor documentation situation (even though I think some people are on the right track!). If I’d known that all we needed was a good looking RDoc app, I could’ve fixed the […]
Jeremy McAnally said,
July 25, 2008 @ 3:01 pm
Sorry I didn’t respond here. I told lifo they looked awesome, and they do. I’m actually really excited to see an updated testing one, because that’s something that’s not covered very well end-to-end anywhere except AWDwR. Good job on those. Seriously!
The whole point of my blog entry is to get a lot of people involved in the writing and editing of these sorts of things; I’m glad to see some momentum behind them because for the longest time we’ve leaned on blogs to provide this sort of thing.
Keep up the work!