Ruby on Rails documentation has been a source of frustration for many developers.

The official docs at api.rubyonrails.com are a great start. They are generated using RDoc. It’s a pretty slick system that extracts comments embedded in the Rails source code and turns them into HTML pages. Since the documentation exists with the source, it’s easy for the Rails Core team to review the docs while coding and to make quick updates when the source changes. And it’s just as easy for the HTML documentation to include the relevant bits of the actual source code for review.

But there are a few drawbacks in the official documentation too. I’ll review these problems, their solutions and how you can help to improve Rails after the jump. I’ll also show you how you can generate a portable, “offline version” of the documentation.

Problems with the Official Documentation

First, it puts the burden of documentation on the Rails Core team. That’s good because they know the most about it, but it’s bad because they are very busy people whose time is better spent on making Rails even better.

The online documentation only shows the current API. It doesn’t provide any way to view previous versions of Rails.

With RDoc, it’s also possible, maybe even desirable, to suppress parts of the documentation. Developers wouldn’t want the docs to contain all those little internal methods that they can’t call anyway. But that leaves the API documentation with some mysteries. You’ll be reviewing the source for a method and it will call another method that you you can’t find or review. As a result, the documentation gives 100% of the “top level” of the API, but only 50% of the source below that.

The online documentation also doesn’t allow for community comments. In my opinion, community comments are a real strength of the PHP documentation. Fellow developers can point out pitfalls, provide best-practice examples, and sometimes even uncover bugs and post workarounds.

Solutions

The Rails community has attempted to remedy some of these shortcomings through a variety of methods. Because RDoc or something similar can be used to syphon the exisitng documentation out of the source code, it makes it easy (maybe too easy!) to get up and running with an alternative documentation project. Here are many of those attempts, I’m sure Google can help you find a dozen more. Some are just better ways of browsing the existing documentation, some allow for community contributions, others attempt to provide more of a tutorial approach.

• Noobkit Docs
• Rails Manual
• Raum’s Rails Reader
• RailDock
• RailsAPI.org
• Rails Brain
• GotAPI
• Rails CHM Documentation

Recently, there has been a push to get more community involvement in patching the official documentation. After all, there is an established tracking system for patches already in place and anyone can submit patches to Rails.

If you want to contribute to the official Rails documentation, the link above will explain the process, but Kevin Clark also wrote up a quick tutorial on how to submit a documentation patch.

The most interesting facet of this effort is the Collaborative Rails Documentation Project. Last year, a group of folks at Caboo.se (headed by Courtenay) started raising money to improve Rails documentation. Their initial goal was to raise $5,000. They had $1,000 in the first hour and, last I heard, they had raised over $16,000. Clearly a lot of folks agreed with them! They are using the funds to hire documentation writers and also giving out prizes to community contributors.

Just last week, they gave an update on their progress and launched The Rails Documentation Project website. The site has their improved API documentation, the beginnings of an open-source book on learning Rails, a collection of documents on single topics, and some community IRC channels dedicated to the documentation project.

Offline Documentation

Some developers have also complained the API documentation is only online. That’s not completely true. Since the documentation is in the source, it is on your computer already. It’s just a matter of knowing how to access it. There are two ways to see Rails documentation directly on your computer.

The first way is to open up your command-line terminal or console and type: gem_server. That will launch a basic WebBrick server. Now open a web browser and go to http://localhost:8808. You’ll see a list of all the installed gems with a link to the RDoc documentation for each. It’s not as pretty as the online version, but it does give you a lot of information.

The second way is to generate the RDoc files yourself. You’ll need to create a new Rails project, then move a copy of Rails into the project directory, then generate the documentation. Here’s what you would type into command-line terminal or console.

The two lines create a Rails project and navigate into it. Obviously, you can skip that if you already have a project. The third line “freezes” Rails to the current version. Rake is a tool for performing some server tasks. Rake makes a copy of the current version in your project directory and tells the project to use that version instead of the main copy of Rails. (Upgrading your main copy of Rails will not change the version of Rails that this project uses.) You can look in the project’s “vendor” folder and see all the Rails source! But instead of digging through the source files, use Rake to generate HTML files of the documentation. And finally, if you want, you can unfreeze Rails so that it will remove the files you just installed and point your application back to the main Rails installation. Look inside the project’s “doc” folder, open “api” and drag “index.html” into a browser. You can move the HTML files in “api” elsewhere to keep them forever or to have easier access.

You can type rake -T doc to see the other documentation you can generate in the same way. You can make documentation for the plug-ins installed in this application (inside the directory “sample_project/vendor/plugins”) and even make documentation for your Rails application!

But what about documentation for Ruby? You can generate RDocs for offline browsing too, but the process is slightly different. From the command-line, navigate to your Ruby installation and run the rdoc command. The -o option allows you to specify the output directory. In the example below, I’m putting them in a new folder called “doc” on my Mac Desktop.

Not only is it extremely handy to have a set of offline documentation, but this also solves the API version problem. The documentation you generate will always be for your version of Rails and Ruby, even if the Rails API and online documentation have changed.

This entry was posted on Tuesday, May 29th, 2007 at 3:48 pm and is filed under Ruby on Rails, Tutorials. You can follow any responses to this entry through the RSS 2.0 feed. You can leave a response, or trackback from your own site.