How Great is Django’s Documentation?

One aspect of Django that never ceases to amaze me, is how well it is documented. I believe this aspect of the Django project got many of us to use it, me included. While doing some boring graduate donkey work, Django’s name popped out, and not surprisingly, as one of the highly documented code bases out there (only projects focusing on documentation came close!). So lets me take this opportunity to thank all those who might be reading this, who had a hand in making Django what it is (Thank you!)

The Lines of documentation to SLOC ratio is plotted against SLOC for 1st of Jan, 2009. Django has one of the highest ratios compared to other open source projects of similar size (See the top part of the Graph). Of course I could have plotted doc lines to SLOC, but then I have to show the deviation of Django from the regression line. This graph just makes it more obvious and is easier to plot:

Click to enlarge, and don’t forget to zoom in.

I also have a few questions should any Django contributors pass by. Any of you guys think that you might have over done it? Is it difficult to maintain the quality of the documentation and keep it up-to-date and did anything change after moving to a regular release schedule? Is it only contributors experienced with the Django code base, who are able to write documentation to ensure quality?

Since I also live in a world where ponies roam and correlation is always seen as causation, let me end this post by saying:

Good documentation is the cause of success for Django, and high ice cream consumption is the cause of increased deaths in neighborhoods with swimming pools during summer!

Add post to:   Delicious Reddit Slashdot Digg Technorati Google
Make comment

Pingbacks

24.08.2011 12:49 Django in 2010: A Round-up | MIH Media Lab @ml.sun.ac.za
he Django documentation.
9.06.2010 0:01 Django in 2010: A Round-up « overflowmedia.com @overflowedmedia.com
he Django documentation.
25.06.2009 20:39 Comparison of KDE documentation with other FLOSS projects « Steveire’s Blog @steveire.wordpress.com
While reading some Django blogs, I came across a post from Mohammad Almarzouq comparing the ratio of Django documentation to lines of code against other Free Software projects.

Comments

Very true, django docs are just great. I can’t tell you how many times I refer to them. Keep up the great work Django devs.

Its indeed amazing. I usually track trunk, and it surprises me how the docs are up-to-date.

From my experience working with Django and making small contributions from time to time I can report that documentation is considered an important part of the project, and there’s an emphasis on providing quality documentation with a new patch. Patches implementing new features are generally not accepted into the code base unless the features are documented (in code and in the external project documentation). The patch is considered incomplete until everything is fully documented. It’s definitely time consuming, but I’ll bet the quality of documentation has a lot to do with the high number of contributors you found in your other post :).

Might be a late response, but what I find amazing, is that even with the constraints on contributing you just mentioned, there seems to be a tendency for people to contribute to Django. More so than other similar FLOSS projects.

The Django community blows my mind! its absolutely amazing.

only contributors experienced with the Django code base, who are able to write documentation to ensure quality?

Thanks for sharing this documentation

The Django community blows my mind! its absolutely amazing.

tendency for people to contribute to Django. More so than other similar FLOSS projects.

Good article.

I usually track trunk, and it surprises me how the docs are up-to-date.

I believe this aspect of the Django project got many of us to use it, me included. While doing some boring graduate donkey work, Django’s name popped out..

the deviation of Django from the regression line. This graph just makes it more obvious and is easier to plot:<a href=”http://www.bringthefresh.com”>how to make money online</a>

Hey thanks for letting me know about this. I had never heard of Django until today.

Thanks for sharing…

it surprises me how the docs are up-to-date.

Required. 30 chars of fewer.

Required.

captcha image Please, enter symbols, which you see on the image