The Paradox of Documentation

When you buy a new consumer product, do you usually read through the manual? What if a small warning on the product says “read manual before using”? (I once bought a stapler that bore this warning. Those things pose a danger of minor puncture wounds to untrained personnel.)

Maybe some strange people do. Once in a while, I will skim through parts of the manual for something complicated like a scientific calculator or a camera. But by and large, most of us tend to ignore the documentation when we first encounter a new product or tool.

What about once you’ve figured out how the product works – do you go back and look at the manual? Do you take notes on how to do things you already do every day?

Maybe that sounds like a dumb idea. But today I’m here to convince you not only that these are worthwhile things to do, but also that documentation gets more valuable the more you know about a topic. I call this the Paradox of Documentation: while documentation is intended to teach or remind us what we don’t know, it is frustratingly unhelpful when we know only a little and remarkably helpful when we know a lot.

Why documentation doesn’t work at first

So assuming you don’t always read the complete manual every time you buy a new product, why don’t you? You might identify some of these reasons:

• The manual takes a long time to read, and I’m busy today; I just want to get this thing working.
• The manual is difficult to understand.
• I won’t remember much of what I read from the manual if I don’t use it a lot right away.
• Reading the manual is much less exciting than experimenting.

I know I’ve justified not reading the documentation for all of these reasons, and probably some not listed here, at one time or another. You probably have too. And, in most cases, all of them are true.

The manual takes a long time to read

Most consumer products, and even many complicated systems like software libraries or cars, can be easily made to work in a basic fashion with a few minutes of experimentation. Reading the manual takes at least that long and won’t save you enough time in setup to make it worthwhile, at least in the short term.

The manual is difficult to understand

When you aren’t familiar with the system, its documentation is necessarily difficult to understand; it is full of terms you don’t know yet and you have to keep looking back and forth between little diagrams and the interface of the device or software because you aren’t familiar with the controls.

I won’t remember much

When we don’t fully understand what we’re reading, retention suffers. Further, we remember things by associating them with things we already know. When we know little about the system, we have few “hooks” to attach the new information to, and we lose it much more readily.

Reading the manual is boring

If you don’t fully understand what you’re reading and the manual is going into great detail on topics you currently know nothing about, it will probably be boring.

Digression: A handful of writers can make even dry technical topics entertaining. They are rarely to be found writing manuals for consumer products, but they do exist! If you’re interested in low-level computer stuff, check out some of Andrew Tanenbaum’s texts on hardware and operating systems. Here are some favorite quotes:

• “Never underestimate the bandwidth of a station wagon full of tapes hurtling down the highway.”
• “In theory, after fully understanding this chapter, the reader should be able to go out and buy a large bag full of transistors and build this subset of the JVM machine. Students who successfully accomplish this task will be given extra credit and a complete psychiatric examination.”
• “The main problem with NFU [an algorithm] is that it is like an elephant: it never forgets anything.”
• “…but process B will never receive any output. User B will hang around the printer for years, wistfully hoping for output that never comes.”

Why documentation gets better over time

Every one of the issues described above is mitigated by experience using the system:

• You can read the documentation faster once you understand the system better, and you can read it when you have some downtime instead of when you’re trying to get something working fast.
• You understand the documentation more easily when you already know the basics (whether the documentation was written for beginning users or not).
• You remember more when you can read easily and you have other information to link the new information with.
• You will find the documentation less boring when you encounter interesting facts or features you never knew about and you know enough to skip over the parts that aren’t interesting.

The remaining question is: why bother? Don’t you already know how to use the system at that point? Well…maybe. But with digital devices or software, there’s usually more than meets the eye. Even seemingly simple devices can hide secrets; did you know, for example, that the backplate on most staplers can be rotated to get the staples to bend outwards instead of inwards, and that doing it this way allows you to comfortably staple through a good ten pages more than the stapler can otherwise handle?

When you’ve figured out how to make the system work by experimentation, you’ve done the bare minimum. But by spending a few minutes now and then perusing documentation, you can learn heaps of useful tips and inside information that will save you time and enable you to handle a wider variety of unusual situations. (And you need to know the tips for best effect; just having them in the documentation often doesn’t help.) Speaking from experience, everyone will also think you’re a genius when you use one of these tips; you just smile and say, “All I did was read the documentation!”, and their opinions still don’t change.

I may have made it sound so far like the only way you can benefit from documentation is by sitting down on your couch in the evening with a glass of wine and the little booklet that came with your TV. If you like doing this, or you end up really bored sometime, go for it; but an easier way to engage with documentation is by consulting it when you have a question. Most people limit their documentation-questions to things they can’t figure out how to do any other way; in contrast, people who understand the Paradox of Documentation and how they can continue learning from documentation consult it anytime they wish there was a better way to do something. That doesn’t guarantee they’ll find a better way, but one thing is for sure, you won’t find one if you don’t look! Surprisingly often, you may find the way you’re looking for, and even if you don’t, you might come away with some other useful knowledge or a workaround.

Documentation need not be limited to the official manual that comes with the device or system. Blog posts, StackExchange questions, and YouTube videos others have made all count as well and make fantastic resources; these also tend to provide more specific and understandable help than official documentation at lower experience levels.

How personal documentation improves too

Control-Alt-Backspace will have much more to say on the topic of personal documentation in the future, but for the moment let me just define what I mean: personal documentation is anything you write that (a) describes how to do a task or solve a problem where (b) you are both the author and the target audience. Some people might call personal documentation “notes,” but I keep so many kinds of notes that I need to be more specific!

Documentation written by you is not subject to the Paradox of Documentation in quite the same way as documentation written by others, because you typically won’t be writing things that you don’t understand or don’t have time to read. Nevertheless, personal documentation diligently updated as you learn more still becomes more useful over time. While you may think you know how to do something after doing it a couple dozen times, working off updated documentation still offers several advantages:

• You are far less likely to slip up and miss a step. (There’s a reason that pilots run through a checklist every time they take off, no matter how much experience they have.) In many cases, careless mistakes actually become more likely the more familiar you get with a process, because you stop paying attention once you know what you’re doing.
• When the steps are written out, it is much easier to identify ways you could improve the process. Sometimes just the act of explaining what you’re doing is sufficient to make you realize you’ve been doing something dumb for months. The more you do something, the more valuable opportunities to improve it become and the easier it is to find them if you only start looking.
• If you do find a way you can improve, you can simply change the documentation and be confident you’ll do it the new way next time. If you’re working from memory, it can be challenging to change established habits even if you are highly motivated – it’s easy to forget you are trying to do things differently.

If you don’t have any documentation like this, you’re missing out! We’ll talk more about how to create it in a future post in this series. For now, your challenge is to embrace the paradox and go read some documentation on a topic you already know about.

---

I will be on vacation the next two weeks, leaving my computer at home to enjoy the “real world” for a bit, so the next Control-Alt-Backspace post will be on June 3rd. If you’re in the US, enjoy the Memorial Day weekend!