Rails documentation

11 Jan 2012

As a Rails developer, I frequently have to check some definitions or get some help about a method or class on the api documentation. In my first months as a Rails developer, I used the official documention, but after some months I discovered other alternatives, which I preferred over the official documentation.

But firstly, what’s wrong with the official documentation ?

Some days before Rails 3.1 release, the official documentation was redesigned and it became so much better than it was, I liked the navigation sidebar, where you can find a method or a class easily. But (and this is IMHO) I still find it very unpleasant to read. However, as an official documentation, it is updated by the same time that the code is released and I expect it to have documentation for “edge-ish” Rails features (there is also a version which is synchronized with rails master branch).

But what are the options ? There is two options that I found out to be great. The first one is Rails Searchable API Doc and the second one is Apidock. There is also another options like RailsBrain which seems to be abandoned (the latest Rails version there is 2.3.2) or to import the documentation into the OSX dictionary which I have not tried it yet.

Rails Searchable API Doc

Rails Searchable API Doc is the documentation I currently use when I develop Ruby on Rails applications. It has a nice look and also have the cool sidebar (by the way, the new design of Rails official documentation uses this engine, but with different colors). It also allows adding the Ruby language documentation and another popular libraries documentations as well. So, as a developer that most of the time uses Ruby, Rails, RSpec and Nokogiri, the possibility of adding this other documentations on the same window is great. Other cool option is the possibility of selecting the documentation for a minor version, so you can select the documentation for Rails 2.3.x, Ruby 1.8.x and Nokogiri 1.3.x. Besides this, we can download the full documentation (including generating a custom package of documentation) to access it locally (if you have a mac, you can use Fluid to setup an App with the documentation. Ok, you can do the same with the Rails documentation, but it is not easy as this. If you like this alternative and you also uses jQuery you can use a similar version to check the library’s documentation.

However, there is some points you should consider when using railsapi documentation: it is not updated as the official one (the current version is 3.1.3 but Rails api is still on 3.0.8rc1, one minor version behind). Other problem resulting of the possibility of adding many libraries, is that the results of a search can show you some irrelevant results, as you can see in the image above.

If you want to access enumerable#merge (which is probably the most popular between these results) you will have to look for results that aren’t what you want.

Api Dock

I used Api Dock a lot, but as I prefer an offline based version of a documentation, I choose Rails Searchable API Doc. But, there is some really nice reasons try Api Dock out.

First of all, it allows people to make comments to make the documentation more comprehensible (there is a nice example on has and belongs to many documentation) and it also allows other people to thank who wrote the commentary. Besides this, it gives you a nice look about a class/method among Rails versions, so you can see the point where something has been added or removed. It also lists some related methods whose documentation can be useful. It is also more updated than Rails Searchable API Doc, as of the time of writing this post, it is on version v3.1.0. It also shows the current status of the documentation, if it is extensive or there is only a few lines of explanation.

One shortcoming of Api Dock is that it is not open source, so you can’t generate it on your computer and access it locally, although it is free (as in free beer) to use. It is also only available for three projects: Ruby, Rails and RSpec and they can’t be accessed simultaneously (which can be bad if you like to see several documentations together but the search results doesn’t shows a lot of irrelevant results).

What about you? What documentation do you use? Have you tried these three I mentioned? Do you want to recommend me another documentation ?