Rails Documentation Projects

Posted by Mike Gunderloy January 15, 2009 @ 09:58 AM

With the recent revitalization of the Rails Wiki project, we’re seeing people ask how the various pieces of Rails documentation fit together. I thought it might be useful to lay out how the Rails Activists see everything fitting together as we move forward.

Rails is a large and mature framework, with a lot of functionality – and with the Merb merger, there will be even more to learn in the future. As such, it presents challenges for developers at all levels trying to understand how to use Rails effectively. There are many resources to help with the learning process, including commercial books and magazines, screencasts and podcasts, tutorials, blog entries, and training courses. But there is also a series of official written documentation projects.

There’s no such thing as one-size-fits-all documentation. Different developers bring different skill sets, backgrounds, and levels of professional maturity to learning Rails. There are at least four levels of official documentation, overlapping but serving different needs:

• Inline documentation, with comments within the code itself (that you can see by running rake doc:rails within any Rails project).
• Rails Guides
• Rails Book (a new project for Rails 3.0)
• Rails wiki

Although at first glance there appears to be substantial overlap, our feeling is that the each of these projects occupies a distinct (and valuable) niche.

RDoc

• Provides immediate help for syntax questions
• Maintained by the actual core developers and generally up-to-date

Rails Guides:

• Provides focused “how to” help for particular problem domains
• Target the mid-level developer, possibly with Rails experience
• Have a large amount of existing high-quality material
• Are already being continuously revised to track changes in edge Rails
• Can include version-specific tutorial code samples
• Can be delivered as a part of core Rails to provide “guidance at your fingertips” for new developers

Rails Book:

• Provides high-level architectural guidance and overview of how the pieces fit together
• Digs into the philosophy of the “Rails Ways”, so readers can understand why the framework works the way it does
• Targets the developer new to Rails or those wanting to go from the “trees” to the “forest” view
• Offers help in conceptualizing Rails and choosing between alternative modules (ORMs, routing DSLs, etc.) in the Rails 3 timeframe
• Can draw on the Merb experience in simultaneous translation and pulling in contributions from many writers
• Largely version independent
• Gives a structured path through end-to-end documentation in a way that standalone Guides do not

Rails Wiki

• Community-driven documentation that can respond rapidly to new software and new questions
• A good repository to links to external information
• Potentially a showcase for Rails itself in the underlying software
• A place to put the accumulated community knowledge, even the pieces that are not often needed

It’s important to note that we don’t see these four projects as entirely separate efforts that have no interaction with one another. In particular, it seems likely that the Book will link to the Guides for those seeking additional detail, while the Guides will link to the Book for those seeking additional high-level guidance. We also anticipate that the wiki will point readers to both Guides and Book (as well as to other sources of information).

So, what can you do to get involved? If you’re a writer, translator, or editor, any of these documentation projects would love to have your help:

• To contribute to the RDoc, write a Rails patch with good comments or check out the docrails project.
• To help the Rails Guides, get in touch with Pratik Naik or Mike Gunderloy, or drop by the #docrails channel on IRC freenode.
• To get involved with the Rails Book, contact Matt Aimonetti.
• To add to the Rails Wiki, join the rubyonrails-wiki group.