a project called Django. Django’s a Python web framework, that came out of a small-town newspaper in Lawrence, KS. Django has a very strong culture of documentation, which is perhaps not surprising given its two original creators have degrees in Journalism and English.
the Django docs, what are they looking for? We can break them down into two categories: * People who already use Django, and are looking for reference material, or an introduction to a sub-component. I’m not going to talk about those users, for the most part, above all else, they’re looking for completeness. They already have a lot of context for anything we tell them. * The other set of users are entirely new to Django. And they want to make a website, that’s what you do with Django.
to the tutorial. You want to make a website. Who are you? What do you already know? In truth, we’ve never been very explicit about the user profile that our tutorial targets. But reading through it one thing becomes incredibly clear: We assume you’re familiar with how the web works.
of effort to make our tutorial digestible to a variety of different people: new to Python, new to databases, new to all sorts of things. But not new to the web. If you aren’t familiar with the request/response cycle, it’s going to be something of a rough time.
it’s made a decision that it’s primarily a tool for people who practice within that domain, not something for other people to use in place of learning about it. ! That’d be a perfectly valid decision, sometimes people don’t care and just want to get something done, but it’s not the direction Django’s gone.
a year, I’ve been working on a Python cryptography library. Developers don’t know anything about cryptography, I don’t know anything about cryptography. But if you screw it up, the consequences are really bad. ! And the feedback you get from users sucks. Do you know what happens when you use a cryptography library correctly? You get random data that looks like garbage out. Do you know what happens when you use a cryptography library incorrectly? You get random data that looks like garbage out. So it’s not like you can count on your users to let you know when your docs lead them astray.
! if you invent the best thing ever and don't write any docs for it for 13 years, you lose — Jean-Paul Calderone This is a thought that informs how I think about documentation. Strictly required. We got into writing this library because we thought the state of the other libraries was bad, but it turns out the state of their documentation is even worse.
question that comes up a lot, particularly when dealing with legacy software. The conventional answer is no, but I think that’s not quite right. When something is utterly unintuitive, we can write docs to tell people how to use it, and they have to follow them. What you can’t document around, is people’s assumptions, if someone thinks they know how something works, and there’s nothing to shock them out of that, they’ll never learn. ! To overcome our egos, we need to be forced to read the docs some of the time.
iPhone? Who here’s read the users’ manual for it? ! Who here works on a product that’s that well designed? We need to write docs for our products. But it’s not all or nothing, docs partner with design to create usability.
to decide who your docs are for. And then write for that audience, and only that audience. “People who use my software” is not an audience. You might need to write some of your documentation multiple times, once for each persona. That’s fine, this way it’ll be useful to everyone. I would much rather write everything twice than write it once and have it be useless. ! The corollary to this is that your users need to end up partitioned into multiple groups, and sometimes it’s tricky to get people to see which group they belong in. ! Our solution to this was to divide the software into multiple layers, one layer which anyone should be able to use correctly, and another “experts” layer.
from top to bottom, like a novel. It’s very popular to write documentation in a reference style, where everything is a link, there’s more info somewhere else. And you need to read that “something else” to get the point. Extra reference links are fine, but they should always be an optional read. If it’s necessary, it goes inline, if it’s optional it can be a link, if it’s just for funsies, chuck it. ! Don’t put digressions in the text, they’re distracting.
should tell you not to use it. It should be documented last, and should come with giant red warnings. Instead it’s just assumed that you know it’s bad. ! Also, if you don’t believe the design and docs are a partnership…
your users. They don’t have the expertise, you do. ! Here’s a typical sentence from most crypto docs: “The choice between AES and ChaCha20 is partially informed by the availability of hardware acceleration, such as AESNI and PCLMULQDQ.” ! Here’s what our docs say: “AES is a good default choice for encrypt.” ! Users who have opinions about the way to do things don’t need you to fill in the gaps, and everyone else will be appreciative of your suggestions.
to do, a lot of the time they’re trying to do the same things, and write tutorials specifically for those, happy users will read those and never read the rest. Reference materials are fine, but they should be secondary to tutorials.
great way to build software, and do everything else in life. Build small, self-contained, components, and put them together to build big systems. ! You need to give concrete examples of how you put the pieces together.
target audience. Make them follow your documentation, to try to achieve some task, and don’t let them use any other resource. Every time they reach for Google, that’s a bug to be fixed. ! If you don’t have a test subject, I recommend being dumber than your users. This is a great strategy which I can personally vouch for.
Donald Rumsfeld, the man can coin a phrase. ! Nothing of consequence should ever depend on something a user doesn’t know they need to know. It seems counter intuitive, but this means that default values can be a bad usability decision, if the user never knows a default was chosen on their behalf, how can they know they need to change from the default?
your tutorial and have something working in 30 minutes. I met someone last night who described their user base as “16 year olds on drugs who want to be Skrillex”. In addition to being the best description of an audience ever, we can all imagine that persona, and it is not a patient one, that’s find though, your users aren’t patient either.. Find a way for them to make something, whatever it is, quickly. People want to do things, and if it’s not possible to do the thing they want in 30 minutes, get them to do something else instead.
care. They don’t care about your domain, your domain is an impediment to their massively fascinating job, and every second they are thinking about your project is a second they aren’t doing something useful with their life, like building a project, learning to juggle, or barbecuing. ! It’s ok. One time, one of them will say thank you, and that’s probably going to have to be good enough. Your software is a means to an end for them.