This post got a bit long-winded, skip to the project announcment if you prefer.
One of the things I love about Python and Django is the philosophy that there is one obvious way to do things. Standards make it easy to dive into other people’s code and figure out what is going on pretty quickly. As with anything under active development, however, those standards are subject to change over time. What was best practice for building sites with Django 0.91 is significantly different than building sites with Django 1.0. Better tools and more experience allow us to refine our processes over time into a set of best practices. While both Python and Django are very well documented, much of the experience and wisdom that is outside the scope of the official documentation is not.
Blogs are Bad for Documentation
Most of this information lives scattered across blogs, mailing lists, books, and the IRC channel. None of these avenues make it easy for developers to learn how to do things the “one obvious way.” There is a lot of stale information floating around out there, some of which we are guilty of creating. We try to blog about how we write and deploy code at Lincoln Loop, but like everyone else out there, we’re utilizing new tools and techniques on a regular basis. Our posts become outdated, but still get lots of hits from users searching for answers. Blogs and mailing lists are great for getting the word out there, but they aren’t true documentation of our growing ecosystem. What’s really needed is a living document.
Sphinx is Good for Documentation
Thankfully, Eric Holscher and Brian Rosner’s Reusable App Docs project got the ball rolling on creating this documentation. It’s focused on giving Django developers a comprehensive manual for building reusable Django applications. Better yet, it is open source and can be generated into any number of formats using the amazing Sphinx documentation generator.
Scratching the Itch
Our team has grown recently and it was important to us that everyone here develop using the same technique and style. Our intranet pointed to Eric and Brian’s project, but quickly started expanding on it. Without realizing it, we created documentation on Django best practices and realized we shouldn’t keep it hidden. I spoke to Eric about forking the project and expanding upon it since our scope was outside of the original documentation he and Brian created. With his blessing we started django-best-practices at GitHub. We’ve started some brain dumps into the document already and hope to chip away at it over time.
You can find a live copy of Django Best Practices at http://lincolnloop.com/django-best-practices/. We’ll still blog about new tips and tricks, but link those posts to the live document so people can always get up-to-date information. If you’re interested in following our progress, you can also follow the project feed.
