The state of Ruby on Rails documentation
Jeremy has recently stated his concerns about the state of Ruby on Rails documentation. It isn’t the first time that people have criticized the documentation, but it is a bit worrisome that people are apparently posting less documentation blog entries about Ruby on Rails. The Ruby on Rails website itself is also in a pretty bad shape: it has many broken links and some information is outdated. (it actually recommends FastCGI as a viable deployment platform 
)
But complaining and criticizing will only get one so far. The best way to improve the documentation is by… well… improving it!
What’s already being done?
People have heavily criticized api.rubyonrails.org. It’s basically just an rdoc dump, and I don’t think it’s that bad. I actually like the javadoc-style usage of frames that allows me to quickly navigate through the different classes of modules. It has no search functionality, but that’s okay because I can easily navigate. I’ve never been a fan of N00bkit or RailsBrain. They look nicer but they’re also harder to navigate because of the way they sort the classes and modules.
Then came Rails-Doc.org. I like Rails-Doc.org. No, I love Rails-Doc.org!
- Its user interface is very, very nice. I like websites that look nice because they actually invite me to read the contents.
- Its search functionality is most excellent.
- It has user comments. I know Noobkit has too, but it seems Rails-Doc.org’s is implemented better.
- It’s being actively developed. I reported a bug in its search functionality, and it was quickly resolved.
- It supports API versioning.
Apart from these, I can’t really describe why Rails-Doc.org is better. It’s a feeling. Maybe it’s because of the way it looks. It just feels more comfortable than the other API doc sites when I use it, and because of that I’m encouraged to contribute useful comments (which I have).
I’ve ditched api.rubyonrails.org completely, in favor of Rails-Doc.org. Nice job, Nodeta! Too bad I can’t use Rails-Doc.org offline.
What can you do?
Posting comments on Rails-Doc.org is nice and all, but one should ideally change the API documentation directly.
A while ago, Pratik Naik announced the docrails project. Anybody can contribute API documentation, just give Pratik a call and he’ll grant you write access to the repository. Every once in a while he reviews the changes and pushes them to the main Rails repository.
Yesterday I tried to write some functional tests for an application that I’m working on, only to find out that the Rails testing manual is outdated and that the API documentation on functional tests is almost nonexistent. So I thought, this is a good opportunity to contribute to docrails. Within a few minutes, Pratik gave me commit access and I contributed some documentation. (more) While I was at it, I also merged some of the user comments that I posted on Rails-Doc.org back to the API documentation.
So, I strongly recommend everybody to contribute. Head to http://github.com/lifo/docrails/tree/master and commit away!
Documentação para Ruby on Rails | development.log said,
July 20, 2008 @ 3:26 pm
[...] também a opinião do Hongli Lai (da Phusion) e do TheWebFellas sobre o [...]
Robin2 said,
July 21, 2008 @ 8:03 am
There must be lots of people like me who would prefer if somebody was paid to write documentation in a useful discursive style with lots of examples.
I don’t know enough to contribute to the documentation.
I have a number of Rails books but (just like books on ASP.net etc) they cannot cover all of the fine details. And it can be very frustrating when something won’t work, but the documentation is not sufficient to explain the point. I’ve come across several cases where there is a variety of ways to use a function, but there is only an example for one way, and often the books use he same examples as the online documentation.
Another thing that appears nowhere in the documentation is an explanation of why features have been included – for example “The purpose of this method is to enable you to do XXX.” That sort of comment would quickly allow a newcomer to decide that this is / is not / the method that is relevant for his /her purposes.