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.Tags: documentation
There is such a thing as too much documentation. I’m all for clarity, but you have to assume a certain amount of prior knowledge.
ME: Click the Right Mouse Button
THEY: What’s a Mouse?
You may think this is a trivial example, but there’s a reason computer programming courses list as their prerequisites: “Must have familiarity with the fundamentals of using a computer, including working with the file system and saving/loading files.”
In a prior lifetime, I worked with a small software firm that needed documentation for their Practice Management product. We found that about 10% of users will actually read a manual. The most effective form of documentation? PowerPoint presentations containing screen shot after screen shot of “do this, click here, type in that.” In other words, a “picture book.” We found that about 40% of all users would use those and benefit from them. By then, dual monitors were the norm, so they would run our program on one monitor and the PowerPoint on the other.
I agree assuming some prior knowledge, but finding exactly how much prior knowledge every user has is the sweet spot good docs should aim for. There’s definitely some things that you can assume that every user will know, including what a mouse is (unless it’s basic computer set up). And to your point about the best documentation, screenshots and good visual representations are the best. Everyone complains about the Ikea instructions, but I think they are some of the best documentation out there. Visually demonstrative, easy to internationalize, and the product is designed with documentation in mind.
“your dumbest user”
Exactly the sort of language that the tech/software world DOES NOT NEED. If you need to spend a whole paragraph redefining the term for the sake of “lexical punch” in your article title, you’re probably doing it wrong.
“Before folks get up in arms about my use of the word dumb, I use it to basically mean …” How about using words to basically mean… what they actually tend to imply to the average person? The word “dumb” tends to mean “inherently less intelligent”.
Take your own advice and use the word “ignorant”, or something like it, when that’s what you actually mean.
I expected better from SO blog, given their efforts to be more inclusive.
Agreed, but it is clearly clickbait. It is also explained in the third paragraph.
It requires some effort to get people to read a blog post about documentation, especially after the Agile Manifesto’s “Working software over comprehensive documentation” has been happily rounded off to “never ever write a single word of documentation ever again” (one of the many fallacies of Agile).
I was about to say the same thing. Never consider users or developers dumb or ignorant just because they do not know a term. This is not about correctness but more about empathy. When we make an attempt to understand why they don’t know or understand a term, it makes it possible to address it more succinctly, while also being respectful and encouraging at the same time.
I really really hope the author considers updating the post.
Exactly what I was thinking. Dumb is just unnecessary. It’s not nice as it implies a beginner or anyone who doesn’t know something is automatically stupid.
Would the word “clueless” be less offensive?
I ran across this blog while researching an Apple issue which I was clueless about LOL!!!
I like it! It’s much kinder
Thanks for the callouts, everybody. I was being a little too spicy in the article and have dialed it back to “clueless.”
Good on you, Ryan! I honestly didn’t expect my comment to even get through moderation. Sorry for the rudeness/snark – it was completely unnecessary and was a knee-jerk reaction coming from my experience of tutoring coders who have confidence issues around not being “smart enough” to learn to code.
Thanks for that. It’s important to note that documentation is often not about being clueless, but about being new and unfamiliar.
I guess the URL can’t be changed anymore, especially after it appeared in the newsletter? Or could it be turned into a redirect?
Unfortunately, the URL is stuck once the post is published.
Honestly, I am dumb, clueless and ignorant about airplane mechanics. I think that the author is dealing with this issue based on the kind of comments technical people say to each other after they are on a call or in a meeting with non-technical users.
A little transparency isn’t a bad thing.
While it is a bit too hostile of a word choice, and likely to provoke a good number of readers, being the dumbest member of a group doesn’t necessarily mean someone is unintelligent; the dumbest Mensa founder is probably still smarter than most if not all of the Stack Exchange userbase. I would honestly consider it the _perfect_ word choice in a void, since the user most in need of documentation is by definition the one showing and/or professing the least intelligence regarding the specific documentation-requiring subject in question.
The problem’s just that language rarely exists in a void, often to its own detriment. Good call switching to “clueless”, it can be really hard for a user to remain subjective enough to keep from seeing “dumbest” as an insult.
I find it odd that, after the many issues Stack Exchange has had relating to pronouns, this article personifies the average expert, not as “they”, but as “she”. Assuming the gender of the average expert, as either male or female, seems strange.
A little “counter bias” to undo centuries of bias probably doesn’t hurt. So long as bias exists, I welcome the use of language which helps to undo it. There’s a riddle that relies on the implicit societal gender bias in the word “doctor” (see below). That bias exists despite the fact that the balances are turning toward the field having more women. The little “surprise” that we get when our assumptions are broken is probably useful in fixing up these assumptions so long as they continue to exist. Ideally they won’t exist for too much longer.
The riddle (probably easy – given the context of this comment): A father and son were in a car accident where the father was killed. The ambulance brought the son to the hospital. He needed immediate surgery. In the operating room, a doctor came in and looked at the little boy and said I can’t operate on him he is my son. Question: Who is the doctor?
Unfortunately, bias cannot truly counter bias; two wrongs never make a right, except if whatever went wrong is perfectly binary. Just as (extreme example, to drive the point in) enslaving every white man on Earth for a year wouldn’t undo even a single day of enslavement or misogynism for even a single early-1800s black woman, biasing one article towards women doesn’t remove another article’s bias towards men. This is the trap that most “equalist” groups fall into, sadly, and is in all honesty more likely to just end up flipping societal biases than removing them.
If we want to end the bias, then we need to start treating people equally, regardless of distinguishing factors; one group _cannot_ receive preferential treatment to another. The issue is that societal bias exists, not that it’s aimed at the wrong group; re-aiming it will, sadly, just end up reinvigorating it with fresh blood. If you want to focus on pronouns, then I would personally suggest alternating pronouns (maybe assume a team of programmers, a guy and a gal?), or using a neutral pronoun such as the age-old singular “they”.
Now, I know this can be hard, and often feels like it doesn’t actually help (to the point where some equalist groups have even been known to protest against treating everyone equally instead of counter-biasing), but refusing to bias articles is the only way to fight back against the existence of bias. Counter-biasing, while it seems like it would help even things out, can only lead to a vicious cycle; eventually the “counter” bias supplants the main bias (e.g., we’d eventually get centuries of assuming the average expert is a “she”), at which point the original bias will just be used to counter it again (e.g., after centuries of “she” experts, we’d get writers who start using “he” as “a little ‘counter bias’ to undo centuries of bias”), in a cycle that repeats ad nauseum. What we need to do is break the cycle, and bias towards “unbiased” instead; if we get centuries of everyone assuming the average “expert” is a team consisting of John and Jane Doe, then the entire concept of “men are better at X and women are better at Y” becomes alien, except for the rare case of fields where there’s an actual biological advantage (e.g., women tend to be better at soprano singing and portraying Wonder Woman, while men tend to be better at bass singing and portraying Superman); unless and until this happens, societal bias will still exist, just a bit more fractured than it used to be. But until then, this is very much a case of the road to hell being paved with good intentions.
[This especially isn’t helped by the fact that a lot of people, deep down (and often subconsciously), want there to be a bias; it doesn’t matter what it is, the mere existence of a bias makes it easier for people to just blame everything on “the other side”, instead of having to actually look at whether they’re at fault. That’s why so many people get up in arms against actually treating everyone equally, even if they don’t show bias themselves, and why it’s so much easier for us to just shift the bias around every so often. I don’t say this about you specifically, it’s something that pretty much everyone does at some level.]
The best way to look at it, IMO, is to ask yourself this: If everyone copies me, will there still be a bias? If yes, then you’re not really undoing bias, just pointing bias in a different direction; if no, then you’re actively fighting against bias.
tl;dr: Adding bias, by definition, cannot make an article less biased. This holds true even if the introduced bias runs counter to common biases, since a bias is still a bias. If we want to end bias, then we need to fight against our instincts and remove as much bias as we can.
[Note: I’m not sure if the previous comment’s formatting went through properly, since the line breaks were missing in the preview. I’m not sure if this is normal or not?]
Counterpoint: the documentation for GCC shouldn’t (and doesn’t) include a full introductory course for each of the programming languages that it supports compiling.
Your article is about considering the least understanding user, then you pick insults and try to redefine them.
The word ‘dumb’ is used as a harmless term by the mass populace, no matter how many paragraphs you write to the contrary. It is used as a mild insult. ‘Ignorant’ means you could understand something but your chose to ignore the chance to. That’s used as a stronger insult. Their value is not in what you try to push, it’s in how the mass populace view them.
I imagine that sometime in the future, it’ll be recognised that mute people shouldn’t be labelled with the same word as ‘idiot’ and the word ‘dumb’ as a milder form of ‘stupid’ will be seep out of usage, maybe replaced by something harmlessly nonsensical. This is similar to how the use of ‘gay’ to mean ‘bad’ by people who are indeed ignorant has been deprecated, which the world is better off for.
Rather than encouraging future writers/authors to take a disdainful view of their readers, why not encourage catering for the least knowledgeable in a positive way. Seems a much better goal for all concerned, no matter how many ‘dummies’ books there are. They’re popular but far from the only books out there.
Correction to my own post – should read:
“The word ‘dumb’ is *not* used as a harmless term by the mass populace, no matter how many paragraphs you write to the contrary.”
This article should be required reading for all CS, IT, MIS, etc students.
My clients are web development illiterate micro-business owners and staff. They start with nothing, and many of them end up doing small coding tasks on their site after a year or two of working with them. My take-a way’s from this process are:
1. Back-off and slow down.
2. Give them real world examples where everything technical matches common activities and situations.
3. Be curious and excited about your work. They will laugh with you and fear will be replaced with curiosity and excitement.
4. Let them ask the same question as many times as they need to.
5. Remind them that they aren’t stupid; they just work in a different environment.
The benefit to me is that I get to rethink everything. That means I’m learning with them.
very interesting. thanks for sharing
commenters, don’t tone police blog articles. please.
StackOverflow tone polices. Karma, friend.
Excellent advice. There’s a name for not heeding it already: being affected by [the curse of knowledge](https://en.wikipedia.org/wiki/Curse_of_knowledge).
This is StackOverflow… why doesn’t Markdown work? Anyway, feel free to fix my first comment and/or delete this one.
Well, this is good, except that I am one of the clueless users! I am just learning how to program in python and I have just submitted a question on it and even that took me sometime to get the question published. I hope someone answers soon. Thanks
I’m a programmer and often read (and sometimes write) documentation.
I’ve never had a “peanut butter and jelly” sandwich by the way, and never seen one in person as far as I know. I don’t even know what exactly peanut butter and jelly is in this context, though I can sort of guess what those might look like. 🙂
Regarding the instructions on creating a peanut butter and jelly sandwich.
Don’t. The very idea is disgusting.
This article, or more specifically the comments section, shows what is wrong with the world today. Instead of trying to understand the points the author is making the majority of comments are on the way he chose to make those points. “I wouldn’t have written it that way.” If you’re a software developer, do you feel good when someone looks at your code and says that? Many of the posts complain about the use of certain words without offering any alternatives. Try being a problem-solver.
But what IS the ‘jelly’ in PBJ? I’m British so I think jelly means something quite different. I thought it was American for ‘jam’ but that is mentioned as an alternative.
FYI – jelly is a sweet flavoured gelatin product, sold in a block to be disolved in hot water then either
a) poured into a mould and left to set then turned out on a plate; such jelly wobbles, it is a treat at childrens’ tea time with ice-cream
b) used to soak sponge fingers for a trifle – sherry optional.
That’s a great point about cross cultural documentation — not everybody uses the same words, another complication for docs. Jelly in the US is a flavored gelatin spread, jam is more of a fruit preserve. In the US, what you’re talking about is generally referred to as Jello or more generically as gelatin. Nobody really calls it that, though. It’s all jello.
I completely agree with the author. I taught in university for a number of years, then went back to study in a different field. Having developed my own philosophies about teaching, what struck me most was that nearly every professor had forgotten what it was like to never have seen the material before. Or perhaps they just didn’t care. There was an impatience and arrogance to their approach that has been the anti-example for how I approach training AND documentation today.
We write documentation NOT for those who know what’s going on even without the documentation, but for those who don’t. As a result, documentation must tell a COMPLETE story, because users of all experience levels will read it. As tedious as writing documentation can be, it’s important to remember the perspective of someone who has never seen your system before…and, perhaps, has never worked on the same TYPE of system before.
This article reminded me of an issue that I still face to this day, even after 15 years of software development.
Software, programming, and documentation are full of words that are not defined to people whose English is a second language.
I had studied English as a second language at school since first grade. By the time I went to university to study computer science, I had had at least 10 years of English education. However, many keywords in computer science sounded alien. They were only defined programmatically, so I had a hard time understanding their relationship to the real world.
The simplest of examples is the “array”. I had never read or heard this word, and neither had my friends. All of us saw it in the programming books first, so we assumed that it’s a keyword, part of a programming-specific DSL.
A practical example showing how people really miss connecting these keywords to real life is in this question, which revived hundreds of votes:
So true! Tensorflow documentation proves the point the best. The SW is awesome yet I dare to say that there is no one on the face of the planet who was able to figure out how to use it reading Tensorflow Docs. It is clearly was written by people who know the product inside out and completely incapable of imagining that other people don’t… Interestingly the coding examples are even denser. Again it is a very well written code yet it requires pretty good apriori understanding of the library
Excellent article Ryan, thank you very much. Being offended by the word “dumb” is dumb itself, we are all dumb about certain topics and knowledgeable about others, and that’s fine, please keep your spicy writting and ignore the censorship.
For a lot of time I struggled reading documentation because I was too busy trying to find how to processes, like how Phaser 3 engine’s docs are very focused on how each module works, while Phaser 3 Rex Notes are very much “hey, here’s how you do this”, now I find myself reading more the original docs because I’m always on the look for that specific information, same happened with other docs such as Django.
IT’S MUCH HARDER TO TEACH INTRODUCTORY COURSES.
As a graduate student I taught courses in intro to linguistics and beginning FORTRAN programming.
In both classes I came to realize that my words often assumed prior knowledge that the students didn’t have. For example, after teaching one quarter of FORTRAN, it finally dawned on me that the students had no idea what a program was! This was the late 70s and no one had computers or cellphones and programmable calculators were still rare. This was the days of punch cards that you submitted to a window and waited for a big printout from a line printer.
The next quarter I started out by explaining what (I thought) a program was and what it did. That quarter went much better.
And people are not used to listening to language the way linguists sometimes do. I remember the oohs and ahhs I got when I pointed out that “to”, “two/too” were pronounced completely differently.
IMNSHO teaching grad students is easy because you can assume they understand you.
I once worked at a place where the technical author made a special effort to ask new employees for their comments on our technical documentation. He took their input very seriously because of their much-valued “ignorance”. I never forgot that.
For someone spending over a decade as a technical writer, your use of semicolons baffles me.
Perhaps you’d like to explain; Criticism without an example isn’t helpful.