Sessions at PyCon US 2012 about Documentation and Django on Sunday 11th March

This talk evaluates a well-known free software tutorial (the official Django tutorial) from the perspective of a web development novice in order to point out omissions and common sticking points and suggest improvements. More generally, this talk is useful to anyone looking to improve their project's tutorials and other newcomer-targeted documentation by approaching them with "beginner's mind".
Abstract

Most free software projects make large, unstated assumptions about the background knowledge and experience of newcomers. Because the people who typically write tutorials or setup documentation for a project are veteran developers intimately familiar with the particulars of the project, it is unfortunately easy to gloss over material or forget the sorts of things that are likely to confuse or turn off newcomers. (How many free software projects assume that newcomers have expertise in bash, or previous experience in distributed version control, or knowledge of how to write a good bug report?) Left to their own devices, everyone designs for people like themselves--not just in software or design, but in documentation as well!

The solution to this problem is twofold: one, ideally, to "user test" one's entry-level documentation by watching a newcomer attempt to use it and note where they get stuck; and two, more generally, to remember what it was like to be a beginning programmer and/or to make your first free software contribution and accordingly to intentionally cultivate empathy for and consciousness of that state of being.

For this talk, we will take as an example the official Django tutorial. Django as a project has a reputation for prioritizing having high-quality and complete documentation far higher than many other FOSS projects. However, despite this high prioritization, even Django's tutorial has significant issues in terms of how well it serves new web programmers; it is primarily targeted as experienced web developers and operates better as an advertisement rather than as a how-to. As a result, it misrepresents or omits entirely whole swaths of knowledge which would be key to a newer web developer actually succeeding with Django.

In this talk, we use the perspective of a web development novice to go through the official Django tutorial, point out omissions and common sticking points, and suggest ways to improve.

Outline:
Our hypothetical newcomer
Imagine a novice programmer--let's say, a CS undergraduate--coming to the Django tutorial for the first time
Fluent in Python and perhaps a couple other languages
New to web programming
Little experience reusing other people's code
Lots of experience using web applications, some sense of their user-facing capabilities
No direct experience using SQL / databases
Critical look at the Django tutorial
Missing concepts

Projects vs. apps: "what's the difference, and why do I care?"
Relatedly, reusing other people's apps -- resources and best practices
Test driven development -- "what's this tests.py thing for?"
Missing features

The biggest "gotcha": handling database schema changes (aka "What do you mean I can't edit my models anymore?")
HOWTO debug -- "what do I do when something goes wrong?"
User-facing CRUD -- Tutorial emphasizes built-in admin, but most modern web apps focus on user-generated content instead; "how do I do that in Django?"
Static file handling and template inheritance -- what would a "Django for designers" guide look like?
Assumed knowledge

HOWTO install Django safely (e.g., virtualenv)
HOWTO deploy to an actual server (even "just" a hosted cloud solution like heroku or ep.io) -- aka "How do I show off this cool app I made to my friends?"
Historical perspective on why the tutorial is this way
In 2005, Django's audience was mostly intermediate-to-advanced programmers who were familiar with older, more minimal Python web frameworks
Django was originally developed for newspapers, hence the admin app emphasis
Lessons
Remember, and be empathetic to, the kinds of mistakes you used to make before you became an experienced coder. Don't remember? Find someone who does!
Link to third-party add-ons that improve the project (e.g., South for migrations)
Be aware of your dependencies -- not just technical ones, but knowledge ones as well
And link to third-party tutorials or other resources that teach those well! (e.g. debugging tools, deployment info)
A tutorial can't cover everything, but it can at least mention nearly everything, with links for further details. A newbie doesn't know an important aspect of your framework exists unless you tell them--blind searching doesn't work very well.
Know who you are writing for -- and say so.