Rails and Django - Documentation (part 12/15)

A technical manager's guide to evaluating web development frameworks, with a detailed review of Ruby on Rails and the Django (Python) projects. (Start here: Whitepaper index)

Documentation

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

Opinion

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.

Documentation	Rails	Django
User manuals and tutorials	very good	very good
API reference	good	good
Books	several	one, in draft
Community wiki and how-to's	good	good
User blogs	many	some
Screencasts	some	limited
MY RATING: (1=worst, 5=best)	4	3

< prev next>

Rails and Django - Documentation (part 12/15)

Posted by: Henrik Lied on July 31, 2007 07:40 AM

I think it's rather unfair to say that Rails' documentation is as good as Django's. The Django Documentation *far* outscores that clumsy API-*manual* of Rails. I agree with you that the lack of screencasts is rather annoying.

Rails and Django - Documentation (part 12/15)

Posted by: Batiste Bieler on December 09, 2007 09:05 AM

I agree with all your points but i completly disagree on this one. I had realy hard time with the online documentation of Rails. The API documentation remind me the terrible javadocs. It's not usable. Toturials are a bunch of article here and there. seriously? Django documentation is, IMHO, more user friendly. It's centralised, well organised and up to date. Tutorials are very well written. Screencast for Django are lacking, but for me it's more a marketing material, not a real piece of documentation.

Rails and Django - Documentation (part 12/15)

Posted by: linoj on December 09, 2007 04:54 PM

Batiste, if we only look at official online docs, I completely agree. But the big picture is more than official docs. The Rails community is pretty prolific (for example, contributed tutorials http://railsforum.com/viewtopic.php?id=6790). Also tutorial screencasts can be very valuable to developers, not marketing (see http://www.railscasts.com/)

Rails and Django - Documentation (part 12/15)

Posted by: Alberto Carvalho on January 04, 2008 07:13 AM

Documentation: Rails 4 x 3 Django. That's not correct. Please, revise this!

Rails and Django - Documentation (part 12/15)

Posted by: Brent Larsen on June 25, 2008 01:35 AM

Yeah, I agree. its more like 3x4 instead of 4x3. the agile rails book is out of date, the scaffolding commands in the first few chapters completely fail and dont even have a decent work around, you just have to skip that section, except the whole book builds on it. Rails doesn't remain backward compatible with itself from version to version, and so many tutorials are out of date or don't even work anymore. Also, most rails tutorials are built around magic, so if you need to do anything more than what the tutorial shows, you are up a creek without a paddle because moving from magic to solid ground is difficult. The django docs are easier to traverse after you have read them. When you go back to repeat on another project, it is easy to find the meat in the django docs, they are just laid out better and separate the discussion from the action so it is easy to find the parts that you need later. They do a better job of hitting related topics all at once rather than sprinkling them all over the book so you never find them once you have read them the first time. Both do a good job of explaining with real world examples. I'd give 100 books that suck for one that is worth reading. Quantity of "documentation" is irrelevant, if not an actual hindrance. Up to this point, I have agreed 100% with every rating, but this one is off, you should fix it. Also, I wouldn't mind if the one about admin frameworks was updated now that both have had time to stabilize a bit. newforms is out, and rails has had time to clean up to. an update there would be nice (they are certainly better than 2's)

Rails and Django - Documentation (part 12/15)

Documentation

Opinion

Rails and Django - Documentation (part 12/15)

Rails and Django - Documentation (part 12/15)

Rails and Django - Documentation (part 12/15)

Rails and Django - Documentation (part 12/15)

Rails and Django - Documentation (part 12/15)

Post a new comment