Time for a Django Documentation Evolution

As Django continues to mature - or more importantly as it captures more media mind share - people from many different camps will want to see what the hype is about. For those entrenched in another platform or web framework, comparisons will be made between features and methodology. For those new to web development, a desire to feel like one is grasping the basics and getting tangible results without a big learning curve can have a big influence. IT managers and system administrators will want to confirm that it can be deployed and scaled without hassle (or conversely they'll be desperately looking for reasons to justify extending their $100,000 proprietary licensing and support fees for another year).

In each case, an important element will help the investigative process: accessible relevant literature. What about the Django documentation? What about the Django Book? Yes they are both excellent resources for the community and I would advise that you read every single page of both at least once if you plan to utilize Django for the long-term. The current stock of documentation is already a big reason that people feel comfortable investing time in the framework and the developers should be given tremendous credit for making documentation such a high priority (probably helps that they also work in journalism). What the current documentation does best is describe what is in the framework and how it works. I think what is missing at this point is pieces of information that address common stumbling blocks that occur in each of the generalized camps:

The Accomplished Beginner:

I finished the tutorials and I'm writing my first app. I was noticing in the documentation about writing your own template tags and context processors and what-not. I feel like these could be useful, but why should I use these when I already have all my application and presentation logic in one place in the view functions?

The ASP.NET/Struts User:

Where are the page objects? I'm used to having nifty little components with events and their own persistence capabilities. Django's presentation layer seems like nothing more than a glorified token-replace. Where do I put my code-behind? It seems like something is missing and I'm afraid I'll lose productivity.

The System Administator:

Just send me a ticket with what you need installed and please try not to bother me anymore today. I have real work to do. (just kidding) How do I setup nginx? What kind of performance can I expect from Apache? I've never hosted a Python environment before - what tuning on the server and network architecture should I be looking at?

Everyone has access to the same documentation (literally, since the book is free online!), but we notice that the questions that need to be addressed are specific to each camp. The beginner doesn't necessarily know which questions to ask. The seasoned developer coming from another platform easily picks up on what hooks Django provides and how they work. They want to know how the terminology from their platform translates and how they can transition their knowledge of design philosophies from one framework to the next.

Now that the framework has been out in the wild for long enough for users of diverse technical backgrounds to take a look at it, I believe there is a large body of undocumented knowledge out there that would help each of the camps. It is time for an evolution in the collective documentation base to help better connect with the different types of consumers or potential consumers of the framework. I think the user community can and should bear the brunt of placing these nuggets of knowledge into the public domain. James Bennett is a real role model in this regard. He has successfully identified these types of gaps in documentation and his excellent articles have made the lightbulbs go on for many who were struggling to apply the framework concepts to their own projects.

This article kicks off a series of articles that will try to identify what some of the many remaining gaps are and add my own paltry contributions to the mix. I will be focusing mostly on general advice on how to structure your code to in order to take advantage of the hooks Django provides. I will be borrowing heavily from the writings of others and attempting to collect and present various nuggets of information I have found in a way that makes sense to me and hopefully helps a few others.

<<     Back to Unbracketed Home Post a Comment Now 1 Comments Below

Comments