Last week Jeremy McAnally talked about the continuing decline in Rails blogging. Like many Rails developers I’ve learned a lot from blogs over the last couple of years: in the early days it was pretty much the only way to find out about how Rails worked as the official documentation was poor to say the least.

In my opinion though, the future for Rails documentation is not as bleak as Jeremy suggests. Less blogging could simply indicate a move towards better quality postings: I’d rather have a choice from a handful of really well written blogs than the hundreds of “OMG!!! Look how awesome Rails is…” style posts that I used to have to trawl through – less hype and more substance is definitely better.

The official documentation is, at last, being improved too: as announced in May there is now a docrails branch on Github and it has already seen a huge number of changes committed.

While I don’t particularly miss coding in PHP it came as quite a shock when I made the move to Rails to find that there wasn’t anything that came close to its documentation. Not only is there a language reference, full documentation for the standard extensions (and with the crazy lack of naming conventions or namespaces in PHP this is really useful!) there is also the invaluable comments section where other PHP developers can contribute extra documentation to each and every part of the language.

This is what Rails has needed for a long time. The great news is that thanks to the hard work of the guys at Nodeta it has finally arrived: behold Rails-doc! The site reached version 2.0 last week and now it has pretty much everything you could ask for:

  • Full documentation of the Rails API including different versions of the API.
  • User comments.
  • Easy to use search, as well as a Firefox search bar extension.
  • A simple, clear user interface that is far better to navigate than the official API documentation.

Now, perhaps more than ever before, we as a community can get involved to improve Rails documentation: we can of course continue with our blogs, but we can also submit patches to docrails and post comments to Rails-doc. These things combined should ensure that we don’t reach the point where, to quote Jeremy, Rails becomes an esoteric project doomed to eventual abandonment because everyone has to shell out $40 for a book to learn how to use it.