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!
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.
Yeah same here.
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.
Thanks for sharing this documentation
The Django community blows my mind! its absolutely amazing.
Good article.