doc-rails

It's been a few weeks working in doc-rails.

The Rails API lacks writing conventions because that's the aggregate work of a lot of people. You know, different tenses, lack of consistent typography, etc. The purpose of this project is not necessarily to fix that, though I'd say that's within scope, but when you revise and write new documentation you need to make choices. So one of the first things we did was to write a few guidelines.

Now, there's a lot of work to do and by now there are systematic revisions going on (that is going file by file in some Rails module), new documentation chunks here and there, tweaks, and transversal revisions (me myself grepped the source tree to find symbols in regular font for example). We monitor and fix doc patches in Rails Trac as well.

Once a week Rails core member Pratik merges the changes into Rails edge.

Being able to contribute to this project is great because you know, if you find something to fix you have the mean to do it right away. A few days ago for instance I wanted to understand a patch to ActiveRecord::Associations::AssociationProxy, and that class lacked documentation. I needed to figure everything from the source code. Not the following guy! I sat down, wrote it, and git pushed. That's fantastic!