Documentation Drive

Whilst this isn't the usual flavor of core chat, I believe that the documentation of Rails is on-topic with this group, as it's just as important as the code and patches usually discussed.

I've decided to start a documentation drive for the month of December and maybe even January. I plan on working full time on the documentation of Rails code and the ecosystem around it, beginning perhaps with an update to the Rails Configuration guide for Rails 3, the initialization internals guide, a guide on using templates and builders and then anything else the community wants.

In order to survive the hot summer in Australia I'm going to need some dollars. I know most of you can't donate your time because you're working your asses off elsewhere, so how about donating some money to me to work on this? This work will greatly benefit the community and I need your support during this month.

You can pledge it here:

Thank you!

I agree that the new rails 3 docs need a lot of work compared to the 2.3 branch. Methods like before_filter for example, don't even appear in the api docs in the methods pane. And I'm pretty sure a lot of other methods are hidden away in dependent gems now, so they don't show up as core Rails methods anymore. I generally load up the 2.3.x docs if I need to get info on rails 3 methods cause I just can't find them anymore. Rails 3 docs are just not in a good state right now and I'm not sure how a n00b is able find anything now, so this "drive" for improvement is extremely welcome. The rails guides though are quite nice, but those only cover very specific slices.

Yes, the before, after and around filter documentation is lacking because they’re class eval’d. I have no clue how you’d document something like this, but I can imagine its exceptionally frustrating for newbies to go to find these methods in the API.

Why is it done this way? What magical abilities are offered besides having shorter code?

I'd be up for helping to write some of the docos if you come up with a list of things that need to get done as well as donate a little bit of cash.

Thanks, mike