New Life for Product Documentation

Universal Usability

Putting people at the center of design

A column by Whitney Quesenbery
August 14, 2006

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.

Sponsor Advertisement
Continue Reading…

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.

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.

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. 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.

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. 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. 

Principal Consultant at Whitney Interactive Design, LLC

New York, New York, USA

Whitney QuesenberyWhitney is an expert in user research, user experience, and usability, with a passion for clear communication. As Principal Consultant at Whitney Interactive Design, she works with large and small companies to develop usable Web sites and applications. She enjoys learning about people around the world and using those insights to design products where people matter. She also works on projects with the National Cancer Institute / National Institutes of Health, IEEE, The Open University, and others. Whitney has served as President of the Usability Professionals’ Association (UPA), on the Executive Council for UXnet, on the board of the Center for Plain Language,and as Director of the UPA Usability in Civic Life project. She has also served on two U.S. government advisory committees: Advisory Committee to the U.S. Access Board (TEITAC), updating the Section 508 regulations, and as Chair for Human Factors and Privacy on the Elections Assistance Commission Advisory Committee (TGDC), creating requirements for voting systems for US elections. Whitney is proud that one of her articles has won an STC Outstanding Journal Article award and that her chapter in Content and Complexity, “Dimensions of Usability,” appears on many course reading lists. She wrote about the use of stories in personas in the chapter “Storytelling and Narrative,” in The Personas Lifecycle, by Pruitt and Adlin. Recently, Rosenfeld Media published her book Storytelling in User Experience Design, which she coauthored with Kevin Brooks.  Read More

Other Columns by Whitney Quesenbery

Other Articles on User Assistance Design

New on UXmatters