Documenting Domain Specific Knowledge

As delivered at Write the Docs North America 2014

Transcript

1. Hi Hi everybody, my name is Alex, thanks for coming to listen today.
2. I got my start writing software, and writing documentation with 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.
3. Why do people come to Django? When people come to 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.
4. Tutorial: Part 1 So you’re fresh to Django. You come 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.
5. Who are your users? We go to quite a bit 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.
6. Our domain Django is a tool within a domain, and 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.
7. Documenting Domain Specific Knowledge This talk is about writing documentation for very narrow domains. The use cases that have inspired this talk are writing documentation for developers, but I suspect there’s useful things here no matter who your audience is.
8. What’s a domain? So, what’s a domain? A domain is anytime a person can be totally ignorant about a subject, while being an expert in everything else. ! I’m particularly interested in documentation for domains where people want to remain ignorant.
9. My motivations Why do I care about that? For nearly 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.
10. So documentation is important… So we’re writing this software, because that’s what we know how to do. But we’re also writing documentation, because this is an education project as much as it is a software project.
11. it might be the best thing ever but guess what ! 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.
12. Can you document around a usability problem? This is a 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.
13. Documentation and design are a partnership Who here owns an 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.
14. Concrete advice Ok, enough platitudes. The rest of this is some practical advice I have on how to write docs for your domain, when your users want to not care.
15. Pick an audience. ! Any audience will do. You need 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.
16. Straight line docs The best documentation I’ve ever read, went 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.
17. No assumptions Your documentation should assume complete and total ignorance. If you’re using jargon, explain the jargon, but even better, don’t use the jargon at all. No one needs to know that your encryption is a “bijective mapping”. Let’s see some examples.
18. Here’s some docs for another crypto library. It explains the initialism, but shoves the details out of line, when they should be front and center. Gotta love “Do not use this” docs.
19. See this first item. It’s really bad, totally insecure. It 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…
20. So what is the default? The thing we just said is bad. Do you think most users even make it to this part of the documentation? Nope, they just stick to the default, on the assumption it works. Nothing you write here will save you.
21. Be prescriptive You are the expert, make strong recommendations for 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.
22. Enable use cases Figure out what your users are trying 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.
23. Composition is great ! Connect the dots Composition is a 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.
24. Get someone to test your documentation Find someone in your 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.
25. Known Unknowns and Unknown Unknowns Say what you will about 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?
26. Always be improving Every time a customer asks you a question, it’s a chance to improve your documentation. ! I’m from the open source world, so the corollary to this, for me, is that you need to use tools that let your users contribute back.
27. Give people easy wins Someone should be able to follow 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.
28. Your users will never say thank you They do not 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.
29. I’m Alex Gaynor https://speakerdeck.com/ alex My name is Alex Gaynor. I work at Rackspace as a software engineer, and I’m an active member of the Python community. You can find the slides for this talk at that URL.
30. Thank you Questions? Thank you very much for listening. Questions?