Tales from documentation: Write for your clueless users

Before I came to Stack Overflow, I spent over a decade as a technical writer. During that time, I wrote for a wide range of readers: non-technical folks in a mail room trying to get this damn software to work, accounting experts looking to reconcile investments, external developers trying to implement API, and internal engineers looking to spin up one or more services. While there’s a wide range of what all these readers know, the documentation produced needs to target the person who knows the least in your user set. 

That’s not to say you ignore the expert, power users. There’s an eternal debate among anybody who writes documentation about how to balance the needs of the beginner and expert. The beginner comes at your material empty and fresh, without any knowledge of the software (and possibly of the domain that the software covers). The expert knows what she’s doing, except for this one thing that she’s trying to sort out. But both users are clueless when it comes to the information that they need. Different users, different levels of clueless. 

The definition of clueless

Before folks get up in arms about my use of the word clueless, I use it to basically mean ignorant. Being ignorant—without knowledge—in areas is no crime, no shame. Recognize where you are clueless and you take the first steps towards finding a clue.

We’ve all come to that moment where we don’t know how to use something, solve a problem, or deal with an error. Call it a lucky guess; most of you discovered this post while looking at a Stack Overflow question. You may have found yourself stuck and hit the search engines looking for answers. If you’re lucky, the result may have been the exact question you have. Congrats! You found someone who was once as clueless as you are now.

The answer you’re hoping for is something of a cure for your ignorance—the clue that solves the case. Good documentation should do the same thing; it should target specific bits of ignorance and try to cure them. But finding the right dosage of information to cure them can be harder than it seems; you may not even be aware of what information your reader is missing. 

Discovering assumptions in a PB&J sandwich

One of the first exercises I did in my first technical writing class was write out instructions for a peanut butter and jelly sandwich. For Americans, this is an activity that we’ve done hundreds of times, so writing out the instructions should be a snap. Put peanut butter on one slice of bread, put jelly on another, slap them together, and BAM! Sandwich accomplished. 

This exercise has become a classic technical writing exercise because it’s a trap. The simple instructions above hide a lot of assumptions. How do I get the peanut butter and jelly out of the jars (assuming that your reader knows what these are and that they come in jars)? Do you drop the contents on slices of bread in lumps or is there another action? How do you manage the one bread slice when you’re spreading on the other one? Do you put it jelly-side up or down? Does it have to be jelly or is jam okay? How about marmalade? When you press the slices together, does it matter which sides are touching?

You may think this is overkill. You may think, well, of course they know not to put the bread peanut butter side down. However, every time you make an assumption like that, you are inviting your reader to screw up. Your most ignorant user probably knows what a sandwich is, but if they are looking for instructions on assembling the easiest of sandwiches, you shouldn’t assume that they know much more than that. 

I remember reading an IT call desk horror story site early in my college career. The story that stuck with me was about a caller baffled by their desktop computer in a computer cluster suddenly shutting down. IT support went through the checklist: make sure your monitor is on—press the button, nothing happens—make sure the computer is on—press the power button, again nothing. The support person says check the power cord in back and make sure you didn’t dislodge it. The user goes back there and says I can’t see anything, it’s pretty dark. “Well,” says the poor IT tech with a belly full of dread, “why’s it dark?” Campus power failure. 

While there is usually one way to do things right, the ways to screw something up are infinite. So when trying to document something, you’ll need to dig into your assumptions to figure out where somebody who needs the information that you are providing could use their endless creativity to get it wrong. Your most clueless user might be an expert polyglot coder who is utterly baffled when it comes to the algorithms that you’re describing. 

These assumptions are part of what’s called tacit knowledge. Tacit is the opposite of explicit; it’s hidden and automatic. When you operate using tacit knowledge, you might not even know that you know something. Think of the rules of a language; there are tons of secret rules that native speakers pick up automatically. My mind was blown when the order of adjectives in English was pointed out to me. I’d know when the rule was violated, but I didn’t actually know it was a rule until it was pointed out. 

Those hidden rules—like a desktop computer not working during a blackout—can be the ones that trip up people looking for answers. I always said that my job as a technical writer—in addition to writing the docs—is to be that first clueless user and find all the ways the software could be used badly. I had an unfair advantage, though; I started out more clueless that most developers I wrote for.

Teaching your least knowledgeable expert

When writing for a user looking to be able to solve a problem or complete a process, I don’t think the beginner-expert divide is as big as the debate makes it out to be. The more relevant divide for me has always been between self-directed and guided readers. 

Self-directed readers are easier to serve. I give them reference material that thoroughly covers everything. This is content like interface documentation and API references. What does this checkbox do? What does this field in a return payload mean? What happens when I add this command line flag? Here are the things that our software has, here’s what they do, here’s what they mean. Your most ignorant reader is going to know the basics of the software, but may be completely ignorant about the specific field, including basic concepts that may seem obvious to you, like what the name of the field means. It’s somebody asking, “What is this thing?”

Guided readers are a little harder to address. These are the folks looking for how-to processes, like the peanut butter and jelly sandwich. They aren’t just looking for information, like our self-directed types; they want a result. How do I create a performance report? How do I create a website that lets people buy socks from me? How do I automate testing? Within these questions are hidden assumptions about their own process, so being thorough is key. 

The concerns about the expert reader come down to not wanting to bore them with information that they already know. But remember, whatever your documentation is, your reader comes to it ignorant about something you’re covering, possibly all of it. The solution isn’t to try to guess what they already know and skip that. The solution is to create smaller, more atomic documentation. 

Any large process—say, creating an ecommerce site—is a series of smaller tasks. Good documentation should target the smallest, most atomic processes. That way, your theoretical expert can pick and choose the documentation that addresses the processes that they are ignorant of. 

Look at the questions on Stack Overflow. Good questions are small and specific. It covers a particular concern with (hopefully) an objective answer. When I was writing how-to documentation, finding that specific question was always the holy grail. That’s why we reward a good question the same as a good answer. It may have references to other processes, but we’ve got hyperlinks for a reason. Keep that single process simple and show the way to other information.