4 steps to better documentation: How to get users the exact answer to the problem

368 readers like this.
Typewriter keys

April Killingsworth. Modified by Rikki Endsley. CC BY-SA 2.0.

When people use your software, they are trying to accomplish a goal. They're trying to fix a problem, find an ATM, catch a Leafeon. They're usually not using software because they enjoy it for its own sake. But just because your users are not expecting to enjoy some software doesn't eliminate their feelings about it. They might notice delight if it's particularly well-designed to help them do what they want, but they don't notice neutral emotions, and mostly the emotions they notice are annoyance or even anger.

The most important part of giving people information about your software is remembering that they are using it to get something done, and not that they want to be reading about it.

Few people like reading documentation, and few developers like writing documentation. But documentation saves you from having to answer the same questions over and over for already-irritated users. By the time most people read the docs they have already failed and are frustrated, and no numbers of adorable bullet points are going to make that better. What makes it better is helping them to get the exact answer to their exact problem as quickly as possible. There is an art to that, and it is an art that you can learn. To reduce support costs and user drop-out you're going to have to write some documentation, and I'm going to tell you how to do it as painlessly as possible.

1. Figure out what the question really is

If you don't have users, then find some people who are like your target users. If you don't have a profile and personas for target users, I suggest you need to back up a couple of steps because you're not really ready to start writing user documentation.

Ask your users what they are trying to do with your software. Don't assume you know. Watch them use the product and figure out where they're struggling or confused. You will only know this if you don't help them too much. Keeping your hands and voice neutral when you watch people screw up is a remarkably difficult part of product testing.

Find out where users are helping each other. Stack Overflow is a rich treasure of user questions and assistance. There may be an IRC channel, a Slack chat, a user forum, a well-trafficked physical bulletin board in the hallway. Whatever it is, write down the questions people have asked, and the answers if you can find any. You may be able to do a rough frequency analysis so you can figure out what is confusing folks and what has not been adequately answered by the community.

If you have anyone doing support, this is also an invaluable resource. Go through their ticket list and find out what they are answering, especially problems that are more mainstream and less weird-edge-case. Do you have any feature requests that could be resolved by people understanding how the software worked better? Add that as well.

Narrow it down

Now you have a massive list of questions, almost everything that has ever been asked by users. Take it down to 20 questions to work on right now. Fun fact: The normal distribution curve applies to almost everything, including the questions software users have. If you have a hundred features/installation settings/confusion points and you address the most common 20, you'll be helping the vast majority of people. I think as nerds we have a fascination with the long tail of problems, but that's not where the majority of the problems are.

2. Make answers findable

So now you have 20 questions. Answer those questions in a way people can find and use. You need to make sure you are answering the actual questions as they affect function, and not as they are asked. If you've ever done tech support you know it is hard for people to ask questions in a way that makes sense to system experts the first time around.

Once you get an answer, take a few minutes to test it and make sure the answer actually works before you publish it for the world.

Next you need to make the answers findable. One of the things I've learned over the years is that what your users call something and what you call something can be entirely different, but if you want to serve them, you need to use the terms they are using.

For example, for years Microsoft displayed the Blue Screen of Death (BSOD) when a fatal error occurred. This was a blue screen with an unhelpful hexadecimal dump in white text. Everyone who worked with Windows recognized it. But it wasn't identified that way in their documentation. It is now an index term when you search microsoft.com, but the results still say something less descriptive.

If you want to help users, and they call it a spinning beach ball or a BSOD or a glitch instead of a bug, you're going to have to put those terms in the meta-text of whatever answer you are providing. If it's a useful search term it's absolutely the right thing to do.


So many times, Search Engine Optimization (SEO) feels like a scam and a problem. But it doesn't have to be. In its most ideal form it's the next generation of indexing. You are using search terms that do not appear in your help text to help people find the answers they are looking for. Here's an example:

  • Problem/search phrase: Wallet doesn't fit in bike shorts
  • Your site: RoadID, identification, tags, dog tags, emergency
  • Your SEO additions: wallet, biking, sailing, starts, spandex, reflective

This works because you learn that the reason people want to carry their wallet on their bike is so that people know who to call if they get hit on the road, but Spandex is unforgiving for wallet storage, so they need something small and wearable. That SEO requires a fair bit of human intelligence, but it also makes the site work better for people who want what you have.

3. Group your answers

The FAQ page is often a lazy cop-out and not really helpful. I know that developers often feel they need it, so your goal should be giving people a clue about how to use and understand your software.

Group your answers in a way that makes it possible for people to have answer serendipity: if this one topic they thought was going to work doesn't, the next one on the page might. You can give them search terms around where they're looking, or related features.

For example, maybe they thought they were looking for languages, but they are actually looking for keyboard layouts. If those are close together because it's logical in your software, and also close together in your FAQ, they are now less annoyed. And remember, that's the goal: less-angry users.

4. Tell people what they need to know next

Once you've answered someone's question, that's great. This is your one chance to help them a little more. If your answer is related to another step or question, put that at the bottom as a next step:

Great! You've configured your email settings. Next, set up your two-factor authentication.

Not everyone will click it, but it gives a sequence and a through flow to your documents, even if someone enters randomly in the middle. You've left some breadcrumbs that they can choose to follow.

More resources

These two books are excellent resources for learning the fine art of spending your documentation-writing resources wisely: Badass: Making Users Awesome and Every Page is Page One.

A pink-haired woman with a half-smile looks directly into the camera.
Heidi is a technical writer, speaker, and developer coach who is working on scaling her writing and industry expertise to help more people be better writers. Her current passions include automated documentation, docs-driven development, and sewing pockets into all her clothes.


Oooh, can't wait to see your talk about this at SeaGL

These are certainly good points, though as they say, "the secret is in the sauce."
Many new users often don't frame their questions well, and while you quickly may get a sense of what they don't know, it may take some to and fro to find out what they know, since this may be key to helping them.
I say "to and fro" because it can't be a Q&A like you're grilling them, but more like a conversation that is supportive and encouraging. And aside from solving this one person's problems, this then becomes knowledge that can lead to improved documentation in the ways you outline.

It's certainly true that new users are sometimes unclear on how to frame their questions, Greg, but I think it's also a good time for us to slow down and make sure that we are not pre-supposing a bunch of jargon before they ca even get to ask the question.

It probably depends on the writers, the users, and the tech stack, when it comes down to it. I know that when I started using FrameMaker, I didn't even have the specialist vocabulary to ask intelligbile questions, and it took a lot of patience from the community to bring every new user up to speed.

I'd like our documentation to feel less like patience, and more like transparency. Always an ideal!

In reply to by Greg P

Greg Pittman hit the critical problem--the way the questions are asked. Our vocabularies [developers, coders, nerds, geeks, whatever we call ourselves] have developed radically since we started. What are records and fields? Ask somebody in agriculture. What is SQL? The sound a pig makes when you kick it? (sorry, pigs) Getting at these vocabulary and terminology issues is critical.

Also, we have to resist answering the questions we wanted them to ask, rather than what they wanted to know and understand. XKCD provides yet one more example of the problem,

If you read through more of XKCD comics (you're doing research, not entertainment, if anybody asks) you'll see a lot more such examples. They're so popular, you can find them through Google. Look for "little bobby tables," (no quotes or comma) for instance.

Creative Commons LicenseThis work is licensed under a Creative Commons Attribution-Share Alike 4.0 International License.