Rails and Django - Documentation (part 12/15)
Documentation serves not only its obvious purpose of teaching and reference, but also bolsters the community, helps recruit new users, promotes discussion and quality, and generally helps create momentum that leads to the continued success of open-source software (OSS) projects.
Documentation can be divided into the following areas:
- User manuals and tutorials
- API reference manual
- Community wiki and how-to's
- User blogs
- Video screencasts
In general, the first two "belong" to the project, and are hosted in the project's website.
User manuals are hard to get written, especially in a young project because they depend on developers who just want to write code not documentation. Manuals must address the needs of new users who are not familiar with a project as well as experience ones. Thankfully, both Django and Rails have quite thorough on-line manuals. Both frameworks also have complete on-line API references (automatically generated from the code).
Hardcopy books, typically authored by a core developer and published by a commercial publisher, are a sign of maturity and stability of a project, and mainstream acceptance. Nowadays, PDF versions of books are often available as an alternative format from the publisher.
Rails has several books available, especially those from The Pragmatic Programmer . The popular "Agile Web Development with Rails" by Dave Thomas, and David Heinemeier Hansson is now in its second edition.
The Django Book is in draft and available on-line for review and comment. Some sections are still unwritten. It is being written for Django 1.0 release.
Both projects, having active communities, offer user-written wiki, how-to's and blogs that are easy to search via Google. Also add video screencasts to the list, increasingly popular they are especially effective for introductory demos of a feature or component.
Fortunately, both Rails and Django have done a great job providing documentation, so far. In fact, both projects offer more documentation than most other OSS projects I have worked with.
Django's book isn't finished but it's clearly preparing for Release 1.0. I have experienced intermittent problems access the http://manuals.rubyonrails.com website.
One more thought (as good a place as any in this document)... I honestly enjoyed reading the “Agile” book and learned a lot. Ditto as I watched David Heinemeier Hansson keynote webcast from RailsConf'06 (http://www.scribemedia.org/2006/07/09/dhh). As much as DHH's personality can be annoying, he does give a great presentation and is a "thought leader. So with Rails, we're getting more than a nice framework, we're getting leadership on design methodology and an education...
Then again, the world is filled with lots of really smart inspiring people, and your framework needs to be ready to draw upon a world of resources.
Conclusion: Both projects offer very good documentation, although Rails is more complete. I give Rails a 4, Django 3.
|User manuals and tutorials||very good||very good|
|Books||several||one, in draft|
|Community wiki and how-to's||good||good|
|MY RATING: (1=worst, 5=best)||4||3 |