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.

Example

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.