Documentation Usability: A Few Things I've Learned from Watching Users

by Tom Johnson on Apr 28, 2009
categories: technical-writing • quick-reference-guides

I received another question from John from Delaware. It was actually in his other e-mail, but I neglected to address it because I don't usually spend so much time answering readers' questions. This one, however, addresses a topic I'm presenting on in a usability progression at the upcoming STC Summit in Atlanta.

Concerned about the field of technical writing, John writes,

People don't read manuals -- I'm sure you've heard this one, but isn't it true? I rarely read manuals, not that I don't see their value. Still, I remember a day (you whippersnapper) when manuals could be measured in inches. Not only that, they were on PAPER! *Shock* *Horror* I know people don't read manuals because they're calling me. And it seems the industry has responded to this by printing less manuals, making all-digital manuals, and hiring outsourced help desks to answer questions already in the manual. Will there be a time when manuals disappear? Perhaps my topic focus is too narrow, as I'm thinking of computer manuals, but I digress...

One answer, John, is that even though your customers may not read manuals, your tech support team probably does, which means someone is reading the manuals and using them to help others. But if your users find it easier to call someone, wait on hold for an agent, and then ask the agent a question rather than find the answer in the help, maybe your help materials aren't very usable. Maybe increasing the usability of your company's documentation could alleviate the need users feel to seek answers from another source.

Find Out What Users Want

Instead of exploring methods for making manuals more usable, the real question is why you're making manuals at all if no one is using them. Almost everyone in business knows that if your customers don't want a product, you don't keep buying more of the product and stocking your shelves with it. Instead, you stock your store with products people want. This brings me to point #1: Find out what help materials your users want.

In a presentation that Joe Sokohl made at Doc Train West two years ago. He encouraged writers to do some user research before defining the help deliverables. Go out and contact the users. Find out what they want. If you're not allowed to contact your users, break the rules and call/visit/e-mail them anyway. Then create your help deliverables based on this research.

It sounds simple, but it can be powerful. You can also track what users want based on metrics of what they access online, assuming you track hits. Or you could ask users at the end of training or a troubleshooting session what type of help material they prefer.

Invariably when I ask people how they prefer to learn new software, they respond, "I like someone to show me," or "I like to play around in the system and then ask a colleague if I get stuck." I've yet to hear the response, "I like long software manuals with lots of text in small print." Usually people that prefer this also like to slam their fingers in car doors and chew on tin foil.

Move Help into the Interface

Overwhelmingly, in addition to the helpful techie friend who will teach them everything they need to know, users say they like to explore a system to learn it. We call them users for a reason you know – they like to use things. (If they liked to be called "readers," the situation would be different.)

Almost no one starts out by reading a manual cover to cover before jumping into the application. Yet the big manual seems to be the starting point and default help deliverable that most technical writers create. Technical writers do this even though they themselves don't learn software this way. It's as if we follow an age-old convention out of tradition and expectation rather than logical considerations about actual usage.

When I interviewed Mike Hughes a few months ago for a podcast, he said research shows people are more likely to use help when it's integrated into the user interface rather than delivered as a separate system. People don't like to stop their work to turn to a separate system for learning. Doing this makes them feel that they're stopping their work and being unproductive. For example, they might say to themselves, That report is due in an hour so I better figure out how to generate it in the right format with the right fields. There's no time to consult the help manual.

Hughes encourages help authors to bring help content directly into the interface, so that when users get stuck on a task, the help is right in front of them. He says users are blind to the help buttons and instead respond better to help links phrased as short questions.

For example, suppose you're documenting a financial banking application. On a page about transactions, if a common pain point for users is that no transaction history appears, you can add a short link that says "Where is my transaction history?" Links phrased as questions get a lot more results than help buttons or information icons, which users have learned to ignore.

Provide One-Page Quick Reference Guides

Another point Hughes makes is a rather startling one. He says the conclusion of most studies about how people use help is that people don't use help. This is a fact we like to disregard. You can set up a lab environment that falsely asks users to skim through help to find their answers, but those situations are fabricated. In real-world research, people rarely use help.

Still, people usually have a need for some kind of instruction. I've found that one-page quick reference guides provide exactly the kind of starting documentation that users want and read. Most users rejoice at the site of a one-page instruction sheet instead of a manual. It communicates simplicity and shows them the core tasks they need to know.

I've written a lot about quick reference guides. These one-page sheets are hard to create and design, but users love them. The quick reference guide gets the user up and running in the system with just enough knowledge to understand the basics. Think of any situation in which you bought something new, such as a new lawnmower. You want to get it started and going as quickly as possible so you can mow your lawn, because the sun is out and it's hot. You can probably figure out the rest by yourself, but those first few steps about how to choke the throttle and what levers to pull or push and what kind of oil to use is all the information you need to get started.

Remember that Most Users are Visual Learners

Another key fact to remember when creating help materials is that the majority of people (approximately at 60%) are visual learners. I think help authors with literary backgrounds, who spend their free time immersed in long fiction novels , may forget this. But the majority of your users most likely learn best when they can see and hear a demonstration of what they're supposed to do.

It amazes me how few technical writers create video tutorials for the applications they document. Short two-to-three-minute video tutorials can be your most powerful form of documentation. I routinely receive feedback from users saying they "enjoyed the videos." Almost no one says they "enjoyed the manual."

My help metrics also reinforce the idea that the video tutorials are my most popular help deliverable. This is because videos, especially videos with voice, approximate the user's desire to have a friend show him or her how to use the application.

Video tutorials don't have to be professionally produced to be useful. Users don't require someone with radio-like voice talent and flawless narrative execution. You can achieve the same learning objectives by creating video yourself, using your help topics as scripts, keeping the tutorials short and friendly, and above all focusing on a single task.

The drawback of videos is that they're not searchable (except for the video metadata). And poorly done videos can be really unpopular if they span long periods of time, such as 10 minutes or more. If the user only has a question about one aspect of the application, but it is required to sit through a full-length documentary to find the answer, your user will become frustrated. This is why making your content searchable is the next key to usable documentation.

Make it Searchable According to Your User's Terminology

Most online help tools have built-in search features. However, having a search feature does not ensure searchability. The question is whether your content is search engine optimized with terms your users will search for. Users often operate with a vocabulary different from the project team's vocabulary. As a result, when your users search for how to "change committee views," they won't find what they're looking for in the help because you called it "Modify Global Group Filter."

To optimize your documentation's searchability, you have to learn to speak your user's language. How would they refer to the core tasks of your application? Don't assume that your project manager, interaction designer, or business analyst has already gathered this language foundation and used it to correctly label all the buttons and menus. In fact, you can probably assume that the buttons and labels are actually not the right words to describe the user's tasks.

The best way to gather information about user vocabulary is to get as closely involved with users as possible, through requirements gathering, training, and other research. If you've helped a few users in the past, leverage their debt, so to speak, to get some real-time information about the tasks they want to perform. Find out the business language and jargon they use, the way they refer to processes and workflows.

Write for Frustrated Users

While your users are searching through the help, keep in mind another key factor in the help scenario: your user is frustrated. He or she is a little impatient, possibly angry, and the tension is building with each unsuccessful click.

Remember that little rhetorical triangle your first English teacher explained, with writer, audience, and purpose on each side of the triangle? It's the foundation of all writing, but most technical writers toss this model out the window when writing help. In their minds, the audience is sipping lemonade on a beach in Cancun, casually browsing the help while gazing out at the baby-blue Caribbean sea.

I posted a video a while back capturing my wife's emotional state at the computer when she realized she'd ordered $40 worth of books from Half.com and had them shipped via media mail (that is, irretrievably) to our old address in Florida. She squeezed her hands. She snapped at her children. She looked up in desperation. She sighed and cringed.

Are you writing help that addresses this emotional state? Does your help get right to the point and provide solutions to problems, or does it slowly wade through introductory, obvious-type statements that users already know?

To write for the frustrated user, in addition to focusing on solutions to problems, consider making FAQs the default landing page when users open help. Keep your sentences short and easy to understand. Break up long chunks of text with subheadings so users can skim. Link up related concepts and tasks. Finally, when you read through your help, read it with the same angry frenzy that your readers are in, and see how carefully you move through each sentence.

Adjust Help Based on Expanding Needs

Help is never complete when you send it with the release. You can never know all the possible problems, quirks, questions, and other issues users will face. If you're forced to store your help with your application code, on a server you don't have access to, your help will soon become stifled.

A couple of months ago, I wrote help for what seemed like a simple application that had only a few different roles. On the back page of each role-based quick reference guide, I listed what I thought would be the common questions or issues users might run into. It seemed liked I'd covered all the bases.

The day came when we rolled out the application to two pilot groups of users. I hadn't planned to take notes at all during the orientation to the users, but at the last minute I tore off a couple of pieces of notebook paper and put them in my pocket. During the sessions, the users bombarded us with questions and scenarios we never considered. Question after question, we found ourselves practically floundering for answers. I filled up both pieces of paper double-sided with notes.

When your help lives outside of the application, on a server you have access to, you can make on-the-fly updates based on user needs and questions. You can take the two pages of notes and add them to the help. You can add the FAQs as they pile up. You can address the situations that you didn't anticipate in your original help file because you didn't see the need or you didn't expect that users would have that situation or problem, or you didn't realize the complexity of their roles.

We can never know the entirety of our user's situation, really. We write help as an outsider to a business process, as someone looking through a window. Looking in that dusty window, we can see people moving around inside and we try to write instructions for their tasks, but we can never fully understand and anticipate all the details of their world.

The first month after you release an application, the questions start to pour in, and if you can't update your help to address them, you can only make notes for future releases. But if you can update the help, more users will begin to see that answers are available in the help. Eventually you begin to save yourself or someone else a phone call and time. And your users will feel more confident searching the help because they'll see its value.

Communicate the Big Picture

In addition to providing answers to user questions, one area most technical writers neglect in their help is the omission of the big picture. I used to have an editor who always asked for the "the big picture." The big picture is an answer users look for but rarely articulate with a specific question. Our editor always wanted a workflow or diagram that provided context about what the application did, who it was for, what users did with it, how they used it, and how information flowed through the system.

Since I usually had my head so deeply buried in the application, exploring each possible task and scenario, I often shrugged my shoulders at her request, saying to myself, Who has time to create illustrations and diagrams that provide a conceptual overview of what users probably already know? And then I tried to satisfy her request with a simple overview paragraph at the beginning.

But the more I work on a variety of projects and edit other help material, I realize how easy it is to become myopic about tasks. Just today I was editing a one-page sheet (that someone else had written), which provided a quick reference of some kind. After staring at it for a while, I realized I had no clear idea about how or when people might use it, or even what it would be used for. It wasn't even clear what the tasks were about. The document lacked any kind of overview text that would have oriented me to the content. It didn't have the big picture because the author was so mired in the details, he or she assumed the purpose was obvious.

Observe Users Follow Your Steps

Now, for the grand finale of usability. What you have written may seem completely obvious and clear. You may have triple-checked the accuracy of the steps, made sure each command referenced the right labels and names. But now you must give your help to a colleague (or, better yet, to a user) and watch him or her try to complete the tasks.

When you watch someone try to use your help this way, funny things happen. Your help instructions aren't as clear as you thought they were. Your colleague gets stuck. He rereads the same paragraph several times, wondering exactly what it means. He stares at the screen, trying to figure out where to click. He struggles to understand the terms you've used. He often doesn't do the task correctly or skips over some of them.

The first time I watched a user perform the steps in my help, I could hardly believe it. I noted points of confusion and later reinforced my instructions on those points with additional screenshots and clarifying notes.

Our problem is that we get so familiar with locations of buttons and menus, because we've been using the system for so long, we forget our initial sense of disorientation. By watching users at least try to walk through the steps, it restores our perspective to the first time we used the application, reliving the initial experience, which is often filled with confusion and puzzlement.

The next time you need to have a peer edit your documentation, forget about asking him or her to look for grammar and style. Instead, schedule an hour and request to watch your colleague perform the steps of the help. Sit back quietly and observe. What you learn in one hour will be enough to make you rework dozens of pages.

Conclusion

I've written about eight principles of documentation usability. Here they are in review:

• Find out what users want
• Move help into the interface
• Provide one-page quick reference guides
• Remember that most users are visual learners
• Write for frustrated users
• Adjust help based on expanding needs
• Communicate the big picture
• Watch users follow your help

Tape this list next to your monitor as you work on your help material. None of these points of usability is a simple item you can check off, such as ensuring tasks have between 5-10 steps, that you have an index, or that your topic titles are parallel. Instead, implementing some of these usability principles is hard -- you have to go out of your way, and you may not like the results.

It's a lot easier to seclude yourself from users, sit back, and plug away at a long manual. But doing so leads to the same scenario that John described at the beginning -- users who take a glance at the manual and decide it's easier to just wait on hold for technical support.

Update: I presented on this topic at the STC Summit in Atlanta at a usability progression and passed out the following handout.

Next: 1.6 Starting Points with Quick Reference Guides: Gathering Before Designing