Good technical documentation focuses on the reader, on their needs and limitations, and on helping them accomplish what they set out to do with a minimum of fuss and pain. Too often, though, the documentation shipped with a product resembles a technical specification more than it resembles something helpful. The traditional approach to user documentation is to document everything.
Think about how much it costs to document everything. It takes a long time, which is costly. Then, it needs to be reviewed. Later, once the product is out the door, it needs to be maintained. The icing on the cake is that users don’t read the documentation. They still post to support forums or try to get through to technical support. They complain about how hard your product is to use.
Actually, support forums are a great source of information about what users need to know about your product. Look for the questions or issues that arise again and again, and take special note of the ones that seem blindingly obvious to you. If a question is coming up repeatedly, then something about that aspect of the product is causing confusion for users.
For example, let’s say customers are regularly posting saying they have trouble removing the battery cover from one of the cellphones your company makes. Ask yourself the five whys.
- Why are these people posting these questions? Because they haven’t been able to remove the battery from their phone.
- Why don’t they just press the battery catch? It isn’t because they’re too stupid. No, the people posting in the forum say they press the battery catch but can’t get the cover off.
- Why isn’t the cover coming off? You, the technical person, know these phones and know the covers are easy to get off. Why are customers having such trouble getting the battery covers off their phones? This is when you need to get a new phone, not a development phone, and try to get the battery cover off the phone. Sure, it’s a bit stiff, but you just have to press hard. They’re all a bit stiff to start with.
- Why aren’t customers pressing hard enough? Because they’re afraid of breaking their new phone.
- Why don’t they know they need to press hard? Because the documentation says “Remove the phone’s back cover”. And that’s it.
Because the documentation provides no detail, it makes the process sound easy. Users expect it to just happen and when they have to put effort into pressing and removing the cover, they think something must be wrong. The documentation and the reality of their own experience have parted ways.
Does your battery catch need to be redesigned? If the catch lasts the life of the majority of phones, then of course it doesn’t. A simple solution to the problem is to add to the documentation something along the lines of, “You may have to press the battery catch firmly to remove the cover”. This has the effect of letting users know that applying a little bit of force is normal and permissible.
Asking why is a good way of starting to understand the users’ perspective that doesn’t require vast amounts of resources. Better yet, find a way to get access to a small sample of your users and watch them try to accomplish routine tasks.