This is a long-form version of the talk I gave at PyCon UK 2015. Currently it’s a minimally-fleshed-out copy of my notes, but will receive updates. My (somewhat shouty and terse) slides are available here for download. If video’s more your thing, I’m on the YouTubes.

I want you to document all the things. I want you to write more documentation and I want you to write better documentation.

What is documentation?

When I say documentation, software and product documentation are the first things that come to mind, but there’s not just that.

For example, process documentation. Do you have a job? Does your job have a clear written policy covering expensing conferences? Has someone written down what you should do in the event of a fire in this room? These are all examples of documentation.

Why does documentation matter?

Obviously if there was a fire in here, that would definitely matter, but that’s quite an extreme example.

Documentation is scaling for knowledge

Is scaling your software something you or your company care about? Do you also have good documentation?

The “shoulder-tap” model of “We’ll just ask Alex” DOES NOT SCALE. Sometimes Alex is away, or off sick, or on holiday. Maybe Alex broke their jaw and both their arms in a freak knitting accident - now you’re totally screwed!

We learnt long ago in software that publish-subscribe scales better than individually polling, well hey that’s just like writing documentation.

Sunlight is the best disinfectant

Openness and transparency matter.

Do you have clearly written documentation about how you conduct interviews? Because if you don’t and then you write some down for the first time, you can discover that Charlie thinks candidates who have published code on GitHub are clearly better than those who don’t, and then you can sit down with Charlie and talk about privilege and unconscious and accidental biases.

Seriously, write things down and publish them, especially things everyone thinks they agree on, and you’ll be surprised and amazed at the disputes that arise!

Error messages are documentation too

Write an error message you’ll be able to read and understand at 3am (thanks @ColdClimate). That’s when you’ll want a good error message.

Write an error message someone else will be able to read and understand at 3am. They’ll thank you for it.

Write an error message that doesn’t rely on you having loads of contextual knowledge and experience. If you don’t have that knowledge and experience, you’re most likely to cause errors and need good error messages.

David MacIver has a fantastic manifesto on error reporting that’s well worth reading.

Why is so much documentation terrible?

It’s important to understand why and how bad documentation happens, so you can avoid making the same mistakes.

Nobody wants to do bad work. Nobody sits down and thinks “I’m going to see how many people I can confuse and annoy by being vague and unclear”.

Good documentation requires incentives

Most of the time, you’re not incentivised to produce good documentation.

When you need documentation most you often have another job to do

Sometimes you’ll be reading documentation out of curiosity and general interest.

Most of the time, you’re doing it because you have something to do, or a problem to solve.

You are not looking to improve the documentation. You’re looking to get on with whatever it was that made you need it in the first place.

When you know more than the docs you’ve no incentive to improve them

You’re busy. You’ve got the knowledge you need now. Why sit down and update the documentation, when there’s so much other stuff to get on with.

Good documentation requires empathy

Forget how easy it feels now you know

Two little words spell doom: “It’s obvious”.

You weren’t saying that when you didn’t know the thing. It wasn’t obvious then!

Understand what it felt like not to know

You need to put yourself in a totally different frame of mind.

“Don’t think of pink elephants”.

“You know about the thing! Write about the thing for someone who doesn’t know about the thing!”.

Good documentation is hard

Remember that.

People generally do the best jobs they’re able to with the resources they have.

People rarely have enough resources.

It’s easy to point and say how terrible something is. Nobody does a bad job deliberately.

How to create good documentation?

Don’t just say what, say why

http://randsinrepose.com/archives/the-process-myth/

“Engineers don’t hate process. They hate process that can’t defend itself.”

“If someone asks you a question that affects how they spend their time, their most valuable asset, and you don’t answer the question, you’ll piss them off”,

Assumptions change, axioms change, circumstances change. If you give context and reasoning, the documentation can be updated too. If you say “before deploying this service, you’ll need to run this command, because there’s a bug preventing database creation”, then when we fix that bug, we know we don’t need to run that command any more.

Arbitrary rules and statements easily piss people off. They piss people off even more when they seem arbitrary and wrong.

If you don’t know why, “what” is better than nothing

A counter point to that.

It’d be great to know why I need to run LaTeX multiple times to get a PDF out, but just telling me that I need to is better than nothing.

It’d be great to know why Minecraft on the Pi uses CP437 encoding for text but just knowing that it does would have saved time and frustration!

Checklists are awesome

Atul Gawande’s The Checklist Manifesto

A book about how people benefit from checklists to get processes right.

He’s a surgeon. If he gets things wrong, people die. That’s quite bad. That puts my problems into perspective.

You should take a look at his book, but very short summary, he found checklists were an incredibly useful documentation tool. AND they helped reduce error rates in complex procedures performed under stress.

Whether for an on-call team to know what to look at when PagerDuty wakes them up, or a teacher evacuating a classroom because of a fire alarm.

Simple tool, incredible results.

Stop answering questions

I’m not saying you should start telling your colleagues, or your users, or whoever, to go away.

If someone asks you something, try to answer them in the form of improved documentation.

https://blog.doismellburning.co.uk/questions-are-documentation-bugs/

Pair documenting

This is something I’m still experimenting with.

Based around the idea of pair programming.

Basic principle: pair two people, one who knows about something, one who doesn’t, get them to do it, and get them to improve the docs.

You’ve helped with empathy, you’ve helped with incentives.

Static sites are awesome

GitHub Pages. Sphinx and ReadTheDocs.

Wikis are the RCS of documentation

The Wiki model is “I made some changes, you can revert them if you notice, or add more on top”. The 90s called. That wasn’t a great way to write software, it’s not a great way to maintain documentation.

The model whereby somebody proposes a change, and people discuss it, and maybe improve it, and eventually it’s accepted or rejected; that’s a whole lot better. Whether you’re using patches on a mailing list, or good old GitHub Pull Requests.

You get transparency, you get openness, you get collaboration. You get lower barriers to entry too. You can turn up and go “I don’t know what this sentence should say, but I didn’t understand it, and I think maybe it should say this, but I’m not sure”.

There is no silver bullet!

I wish there was. These are my observations and my opinions. If you’ve got ideas and insights, then please, get in touch!