The Kind of Documentation Users Really Want

by Tom Johnson on Jun 15, 2008
categories: technical-writing

Have you ever asked your users what kind of training materials they want, or how they prefer to learn software? This kind of information is critical to figuring out what help deliverables to produce.

But really when it comes down to it, there are only so many options — printed manuals, short guides, interactive flash guides, videos, online help, live training, reference cards, context-sensitive help, workbooks and exercises, or, usually the favorite, someone to stand by their computer and answer questions whenever they need help.

(I'm surprised how many people actually tell me that last option, as if in any kind of world that would be feasible.)

The most common responses go somewhat like this:

• I like to jump into the application and then turn to the help material when I get stuck.
• I want to quickly search the help to find an answer to my question.
• I would like the videos sent to me on a DVD please.
• I like to mark up the printed manuals with notes and tabs.
• Videos appeal to people who are visual learners. I prefer to have both video and print.

While it seems like such a simple task — ask the users what they want, and then deliver it — in reality it's a difficult call. Imagine that you're planning to feed a large hall of people. In deciding what to feed them, you ask them. But the responses are all over the place: some are vegetarians, some love steak, some prefer barbeque, others want salad, others want pork, others don't eat pork, others like pizza, others want crab, others are allergic to seafood, and so on. Same goes with help.

However, despite the variety of learning preferences, I think there are several key principles that hold true for almost all of us:

• Long manuals intimidate us and bring out a sense of disgust and depression.
• Short quick reference guides, cards, or other quick material give the impression that the application is easy to learn -- therefore we welcome short guides with open arms.
• When we have questions, we prefer to search for the specific answer rather than reading a manual from the beginning.
• When we don't find the answer within 2 minutes, we give up and ask our neighbor or call someone.
• Seeing a process is often much more useful than reading about it.
• Visual images with callouts and other annotations make instructions easier to absorb while scanning, and our primary reading mode for help materials is to scan.
• If undergoing training, hands-on tasks at a computer lab are infinitely more valuable than a long demonstration at the front of the room.
• Videos are helpful, but if they're long, or if the user has no control to skip around, fast forward, or go directly to bookmarks, a long video tutorial (more than 5 minutes) is unbearable.

Given this variety of ups and downs, usability principles and learning preferences, what set of help deliverables will most likely appeal to the widest audience? In most situations, one can't create them all and do a good job. Maybe you're magically able to single source everything into 7 different deliverables at once and satisfy everyone, but in my experience, that doesn't really work.

A Telling Moment

My favorite response to the question — "How do you prefer to learn new software applications?" — was when a user pointed me to the Interactive Microsoft Office Guides. These guides were created my Microsoft to help people figure out where all the supposedly intuitive stuff is on the ribbon (I can just see the Microsoft ribbon developers saying, 3 years ago, "Oh users will get it, totally …."

You might want to take a look at these guides. They're Flash-based, interactive, and really engaging, not to mention helpful. They show a mock interface of the application. When you make a selection, it gives instruction on how to do the exact same task in Word 2007.

My Analysis

When it comes down to it, here's what I think most users truly want:

• A comprehensive online source they can search and quickly find answers.
• Short quick reference guides (about 3-5 pages) in an attractive format.
• Short 2-minute video tutorials for the most confusing tasks.
• An ability to interact or contact a real person either virtually or physically.

Notice that I omitted the M word. There isn't a 200 page print manual in the list. I have mixed feelings about this omission. At the last STC Summit, I attended a panel that discussed whether the printed manual was dead.

Unfortunately there wasn't a definitive answer. When you omit the printed manual, 67% of the people complain, according to the panel. But apparently if you put the manual in PDF format, in place of a printed manual, the percentage of people who use it is exactly the same. So people don't use the printed manual, but they complain if you don't include it.

Creating a long manual is no easy task. To be usable, it needs a meaty index at the back that is thorough, full of synonym references and other user-intuitive phrasings. Additionally, you need cross references throughout. And then there's a lot of layout and formatting. If you have images that you're including, the resolutions differ from online and print, so often you need two sets. In many cases (if you're using a good help authoring tool) you can mostly single source your online help to printed material in one go, but setting up the conditional tags, print styles, variables, cross references, and other considerations in your tool, as well as fixing the inevitable formatting errors, takes a long time.

Rather than labor away at this printed beast, I think I will, for once, skip it and focus on improving other deliverables my users more frequently request.

What help deliverables are you creating for your users and why?