The unhelp files: When documentation fails

In a recent Cisco ASA workshop, one of my students bemoaned a call he placed to tech support. His company is a big client of a well-known security software vendor. He had unsuccessfully attempted to find the answer he needed in their documentation, so he called their help desk. The rep he spoke with berated him for not looking up his solution in the documentation and condescendingly pointed him toward the document with the answer. (There's never an excuse to treat another human being disrespectfully.)

Frankly, most of the IT people I know would prefer anything over calling tech support and only place such a call as a last resort after every other avenue has failed. In this case, the vendor's documentation failed and so did their technical support staff.

I've recently been training myself on software from a well-known graphics software vendor and I've noticed that common, simple things that I want to do are not easily found in their documentation. A quick Google search, however, gets me the answers I need.

What does it say about our help systems that an intelligent, experienced IT pro like my student can't quickly find the documentation she or he needs and has to tolerate a surly attitude to get a solution? What does it say when a major software vendor can't catalog their documentation well enough to deliver meaningful results faster than Google?

It's not that difficult to do it right. It doesn't take much effort to conduct simple usability studies which can produce large usability improvements. Gather some of your users in a study. Ask them to perform the most common tasks with your application(s), using your documentation, and see how it works. Offer cool, shiny stuff as incentives and you'll quickly learn what you need to fix and what you've done right. The Society for Technical Communication has some great docs on their Web site.

Here are five tips for creating usable documentation:

1) Format for readability. Use bold section and paragraph headers to help your reader scan the documentation. Use simple, familiar typefaces such as Arial, Helvetica, and Times. A common practice in print typography is to put section and paragraph headers in a bold, modern font such as Arial or Helvetica and body copy in non-bolded Times. Due to the lower resolution of old monitors, most designers recommend reversing that practice for screen reading. The TNW Design and Dev blog has some good information about how to choose a typeface.

2) Be a crazy linker. In the graphics application I mentioned, I searched help on a particular topic. One of the articles it found gave an in-depth description of the topic, but failed to give me any configuration guidance. How difficult would it have been to include links to the configuration guides?

3) Have someone else test and proofread the documentation. You simply cannot do it yourself. You know what you meant to say, so your eyes will do auto-correct and you'll miss typographical errors and missing or incorrect steps. The other person doesn't need to be technically-inclined, he or she just needs to be someone other than you.

4) Provide numbered, step-by-step configuration guides. The numbering helps your users ensure they complete each step without repeating or overlooking any steps. Numbering also makes the documentation easier to read.

5) Include a link for feedback. Users appreciate a way to offer feedback and you'll get good information about typos and missing or incorrect steps.

Check out this video from the BA collective with several tips on documentation usability:

Perhaps the most important thing to do is spend time with the documentation yourself. Look for areas that need links, references to buttons whose locations are not obvious, and assumptions about levels of knowledge. If you find yourself using a sailor's vocabulary, imagine what your users are saying!

Don R. Crawley is President/Chief Technologist at soundtraining.net, the Seattle IT training firm. A geek and nerdy kind of guy since sometime back in the 60s, today he pontificates at Computerworld, writes books for IT people, and speaks to IT people on customer service, communication, and technology.