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

Your current filters are…

  • Improving Documentation with "Beginner's Mind" (or: Fixing the Django Tutorial)

    by Karen Rustad

    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".

    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.

    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
    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.

    At 1:30pm to 2:10pm, Sunday 11th March

    In E2, Santa Clara Convention Center