New Life for Product Documentation

By Whitney Quesenbery

Published: August 14, 2006

“I’ve seen some signs of life in the use of documentation for digital products recently.”

Here are some “truths” we’ve all heard: “Documentation is just a band-aid for poor design.” “Real users don’t read manuals.” “Super users never read anything.” “Help doesn’t.”

But are they really true? I’ve seen some signs of life in the use of documentation for digital products recently.

“I need it when I do something new.”

In a usability test of some small business financial software programs, we all froze when one participant reached for a fat manual. We were all wondering whether the rest of the session would be spent watching him read through the book, looking for an answer. Amazingly, it didn’t. Within a few minutes, he had found the answer and used it to successfully solve the problem he’d been stuck on.

Discussing this at the next break, we realized that we’d seen many of the participants using the online Help and How To… tips. They turned to them when they got stuck and couldn’t figure out the next step in a task, but mostly, they used them when they tried something new. We started asking about their use of Help. Was it just something they were doing during the test, or was it how they worked in their own offices? In retrospect, the answers were not surprising.

  • Business owners used Help because asking their accountant—a consultant, not an employee—for help cost them time and money. They used this type of software to gain more independence and wanted to figure things out for themselves.
  • Bookkeepers told us that, even though there were other people in the office, this was their area of expertise. They didn’t have anyone to turn to and needed the software to provide on-the-spot instructions when they needed help.

Both groups considered accounting “hard”—that is, something that required training. But they expected—or hoped—that the software itself would provide that training as they needed it. In addition, accounting is very procedural, and both groups were looking for recipes—the right sequence of actions for performing their work correctly.

This is just the sort of assistance that well-integrated online Help can provide very well—especially if it gives links to actions, offers the right kind of help, and makes the information easy to find.

“We just have to do the user research and usability testing that’s necessary to make sure the topics are what users need and are findable and usable.”

It wasn’t perfect. The Help in the programs we were testing didn’t always work well. Sometimes the Help was hidden in plain sight—on the screen, but not visible to the users. Sometimes users couldn’t find the right information, because they were using the “wrong” word, and there weren’t enough synonyms and signposts to lead them to the word the software used. In one case, several people found the right instructions, but because the Help used a different name for a function than the one used on the screen, they couldn’t use the instructions to successfully complete their tasks.

But when Help worked, it was just what these small business owners and bookkeepers expected. We just have to do the user research and usability testing that’s necessary to make sure the topics are what users need and are findable and usable.

“I need to know if it’s usable before I buy it.”

My second encounter with people unexpectedly using documentation was closer to home. My husband is a person who doles out advice on any high-tech purchase to our friends and family—from digital cameras to electronic design software to what email service to sign up for. He was researching programmable thermostats the other day when I heard him muttering ominously, “Cross that one off the list—no manual on their Web site.”

As a member of STC—the Society for Technical Communication, home to technical writers of all kinds, including those who create product documentation—my ears pricked up. My super-geek radio/audio/networking/electronics engineer husband reading a manual? Isn’t he from the demographic that never reads a manual?

It turns out that he’s happy to give advice, but he hates having to teach people how to use their new toys and tools. Before he recommends a product, he wants to see how it works, so he can decide if it’s easy—or “sensible” as he puts it—enough to use. He’s using the instructions in the manual to do a cognitive walkthrough, looking for “convoluted, circuitous paths through function sequences.” This thought experiment is his substitute for being able to try a product out before he buys or recommends it.

I thought this was pretty unusual, but a friend who makes DMXters—software and hardware tools for DMX, the theatrical networking protocol—made Download Our Manuals one of the first links on his company Web site. Besides saving him lots of frantic technical support calls from customers on the road with shows, who haven’t brought along their manuals, he’s also hearing from new customers who have read the installation guides before deciding to order the gear.

“We usually assume that documentation is used after a product has been purchased, as part of the process of learning or setting it up.”

Maybe this isn’t so different from the Amazon feature that lets you LOOK INSIDE!™ to read a few pages of a book you are interested in, providing a bit of the experience of flipping the pages of a book in a real-world bookstore. Or the way Whirlpool provides not only owner’s manuals, but also a “Dimension Guide,” so you cannot only shop for features and price, but make sure that your new appliance will fit in that corner of your basement.

We usually assume that documentation is used after a product has been purchased, as part of the process of learning or setting it up. But these are all examples documentation as part of the purchasing-decision process, looking for information beyond the lists of features or simple technical specifications on data sheets.

Better Documentation or Better Designed Products?

“I’m not suggesting that we shouldn’t be working to design products that deliver a better user experience— especially the initial out-of-the-box experience.”

I’m not suggesting that we shouldn’t be working to design products that deliver a better user experience—especially the initial out-of-the-box experience. As Frances Anderton of radio station KCRW’s DnA: Design and Architecture put it in a post-Christmas-present show, “Why should something as simple as a bathroom scale require a manual?”

Nor do I deny that some product documentation could use improvement. As Ed Baig wrote in USA Today, “Don't expect to be saved by the instruction manual—if there is one. If it hasn't been written by geeks, it's been translated, verbatim, from Korean or Japanese. Too many gadgets pay scant attention to ease of use.”

But since most products have some kind of manual, why can’t we make a better manual? We need to create manuals that take into account how people will use them. We need to design manuals for use when and where people need them most. User-centered manuals. This is not a new idea, of course.

“We need to design manuals for use when and where people need them most. User-centered manuals.”

Back in the dark ages of 1990, John Carroll wrote The Nurnberg Funnel: Designing Minimalist Instruction for Practical Computer Skill, in which he proposed that minimalist documentation should provide just enough information to get users to work more with the product than the manual. A minimalist manual should

  • reduce the amount of narrative text
  • contain modules of instruction that people can use in any order
  • anticipate user errors and provide tips for recovery
  • concentrate on the user’s own tasks

In her chapter in Beyond the Nurnberg Funnel, Ginny Redish talks about “reading to learn to do.” Her point is that people read instructions, or manuals, only to find out how to get something done. And the faster they can stop reading and get back to whatever they were doing, the happier they are.

“The better Web services work this way. They provide minimalist instructions throughout a process, with prompts, additional information to the right of fields, and links to more complete instructions.”

The better Web services work this way. They provide minimalist instructions throughout a process, with prompts, additional information to the right of fields, and links to more complete instructions. They have virtually no long paragraphs of text and concentrate on supporting tasks. It’s time for gadgets and complex software to learn this lesson as well.

Doing this right means thinking about the documentation as part of the product—and that’s harder than it sounds. It means paying attention to how people discover and learn new features as part of our user research, and using the insights we gain to provide the right information in the right form at just the right time. It means testing the user assistance—on-screen information, online Help, printed manuals, and any other documentation—along with the product.

Doing this right also means including people who specialize in technical writing and instruction on a product design team from the beginning. After all, writing an explanation for how to use a product is a good sanity check—if you can’t explain it easily, maybe the design is a bit too “convoluted or circuitous.” And if we think about when and why our customers might need help, we can improve the design to improve their user experience.

5 Comments

I think that technical writers should be brought early into the software development cycle. Because technical writers are thinking from a user’s point of view, they can provide valued insight into the design of the product. It is difficult to pinpoint exactly when technical writers should be involved in the design. It would probably depend on the product. We should nevertheless be considered for our opinion. I find that too many UI designers don’t talk to technical writers nor consider them as peers as they should.

Hi Whitney. I’m finding that I need good documentation when my totally wired 19-year-old daughter is having a problem with one of her gadgets. I don’t even know how to use her digital camera, for example, but when it malfunctions she expects her “geek Dad” to figure out why and fix it (or get it fixed).

On the subject of better documentation, I just got a new cell phone. It came with a chapbook-size printed manual and also a PDF user’s guide. My old phone could be toggled in and out of “silent” mode by pressing and holding the # key. Since the new phone was made by the same company, I figured it must have the same feature. Holding the # key did nothing, so I went to the docs. There was no mention of such a feature or of any keypad shortcuts. I finally got the answer (hold down the Volume Down button for Silent, hold down the Volume Up for Normal) from a guy on a Yahoo group dedicated to that model of cell phone. He had discovered it by spending an afternoon pressing every key combination he could think of. Sheesh.

KW—I agree with you that technical writers should be better integrated into the product team. User experience work is inherently multidisciplinary, and we need people looking at the design from many different perspectives. Unfortunately, it’s especially important for products that have not had anyone really paying attention to the user experience at all. Writing instructions can be a good usability check: If the explanation is convoluted, there’s a a good chance that the design could use a little streamlining, too.

Jim—I think we’ve all felt your pain with one product or another. We buy a new gadget or software or other product and discover that the information we think is most important is just plain missing. Your story is a perfect example of a product team that didn’t do its user research well. Maybe the docs worked well for a first-time mobile phone user, but they obviously failed an experienced person with a set of assumptions about the features a phone should have.

[Dimension Guide link goes to 404 page on Whirlpool site.]

The piece is very well written with many practical insights. Well done.

DMSwanson

Join the Discussion

Asterisks (*) indicate required information.