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.
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?
