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.