The Kind of Documentation Users Really Want

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?

Adobe RobohelpMadcap Flare

By Tom Johnson

I'm a technical writer working for the 41st Parameter in San Jose, California. I'm interested in topics related to technical writing, such as visual communication, API documentation, information architecture, web publishing, JavaScript, front-end design, content strategy, Jekyll, and more. Feel free to contact me with any questions.

  • Kai

    We’re pretty much toeing the line: We deliver online help (as a comprehensive Flare WebHelp including a Quick Start Browse Sequence, or as JavaHelp) as primary deliverable with Quick Start Guides and 100+-page User Manuals and as secondary PDF deliverables.

    Actually, it used to be the other way around with PDF from Word as the primary deliverable, but the resulting secondary online format was neither user-friendly nor maintainable, so we got MadCap Flare and turned the process around.

    We’re quite happy now with the process that supports our primary online deliverables very efficiently. We’ve scaled back and standardized the efforts for the PDFs since getting Flare. They all use the same print style sheet and otherwise vary minimally from the online targets.

    This way we can still placate marketing and sales who are the staunchest in-house defenders of the PDF deliverables…

    We also do a separate 4-page quick reference for one product which is a stand-alone PDF from Word.

  • Nina

    “So people don’t use the printed manual, but they complain if you don’t include it.”

    Bingo. We’re switching to online/PDF manuals this year, and you would not believe the complaints (actually, you probably would). My vision is to produce a series of quick references and short videos to complement our already-good telephone and e-mail customer service. I envision our PDF manual being a secondary (or tertiary) tool. It will still need to be well-written with top-notch formatting, indexing, cross-referencing, etc., but I need to remember that the manual–online or not–is “the book nobody wants to read unless they absolutely have to.”

    Since I don’t have the capability (yet) for videos, I’ve been using a lot of simple, sometimes entertaining flow charts for processes for internal procedures at my company. (These are, of course, supplemental to the “official” procedural documentation that’s required.) I’ve gotten a lot of good feedback on those and will probably be using a lot more in the applicable documentation for our customers.

    Ninas last blog post..Welcome Home

  • Holly

    We are sometimes asked to create a “one-page cheat sheet.”

    But when we ask what topics to include, they throw in the kitchen sink and say, “Put in a lot of screenshots, too!”

    This is why “managing expectations” is important.

  • Joe

    Unfortunately, I don’t get a lot of interaction with my users, which, I feel makes the quality of my documentation suffer. I know what they use the appplications for (most of them anyway, I also document a lot of back-end systems that have little or no user interface), but not necessarily how they use the applications. Most of what I get is through the filter of a marketing person, who usually feel that “more is better.” Holly’s example of users requesting a one-page cheat sheet mirrors what I got when marketing reviewed my QuickStart Reference Guide, which is basically a two-sided one page reference card in column format. It is exactly what it says it is – a QuickStart Reference Guide. Something to help the user get started in a hurry. If they want in-depth information, they can look in the User Manual, or online help both of which are provided with the application. But, my marketing guy wanted to know why I didn’t have more information, more screenshots, etc. To put in all the information he wanted would have defeated the purpose of the QuickStart.

    Anyway, I’ve found users to be of three types:

    1. They try to learn the application on their own, and only look in the manual when they can’t figure something out.

    2. They try to learn the application on their own, and use the online help only when they can’t figure something out.

    3. They try to learn the application on their own, and the first time they get stuck, they call Tech Support.

    I’ve hardly ever come across a user who consulted the manual first.

  • Pingback: A Winner, 76 Years Later()

  • Scott


    Sometimes it frightens me how in sync our minds our. I wrote a post in a similar vein on the weekend!

    This is great post, though. My take: the deliverables will vary based on the product and the audience. There’s really no one-size-fits-all solution.

  • erica

    We plan to do video tutorials (usually about 2 minutes long), cheat sheets with one set of steps per common procedure, and a compiled help file with all the details. They do ask me to export the CHM out to PDF though we all know no one uses it anyway.

  • Pingback: End User Surveys - The Content Wrangler Community()

  • Deb Lockwood

    I thought this was a great post; informative, thought provoking, helpful. I’m forwarding the post to some other folks in our company who have been talking about the same topic. Thanks for your devotion to the profession of technical communication!

  • Pingback: Useful Stuff for Tech Writers « Orion Spur()

  • avi

    Users want accurate, complete and helpful documentation. This is why I tossed single-sourcing years ago.
    If the documentation is helpful, the users doe’t mind reading it on a PDF, a CHM, MOSS, or on an email from me (“the doc is not approved yet, but I’ll let you read these several pages only because you’re such a great contributor to the documentation I write”).

    avis last blog post..הבעיה עם הטיפול בגלעד שליט

  • Tom

    I agree with you in part, but format does make a difference. My experience with help goes like this. I create an online help file, because people like to search quickly for a task. Then someone asks if there’s a printable version of the online help. So I create a manual. Then someone gawks at the size of the manual and asks for a concise version, so I create a quick reference guide. Then some users say they don’t learn from written instructions and want to see the process. So I create video tutorials. It would be nice if I could just point them to one file, but that solution doesn’t work in my experience.

  • Tim Mantyla

    It’s not always easy to determine what kind of user assistance format, publication or website-style help to use.

    I interviewed as many of the potential readers of the online sales training & reference guide before writing it. That way I found out what they wanted and needed “from the horse’s mouths.” They’re the subject matter experts (SMEs) on what they want and need to know. (Company officers may have a somewhat different idea of what they need staff to know.)

    From their answers, and the company’s requirements, I determined that a website-style help system would work best.

    Sometimes you have to imagine you’re a reader or two–or more. Preferably imagine a range of readers/users, from the least skilled and savvy to the most.

    If you can’t imagine being a reader, ask someone you know with a good imagination–perhaps a writer or graphic designer (or a good liar!) to pretent to be your reader, then ask your questions.

    In any case, asking *someone* to be a potential audience member is better than just writing for people you’ve taken less than a minute to stereotype.

    I don’t mean stereotyping in the sense of prejudice or racial/sex/religious discrimination. Stereotyping is a way of categorizing people, things and situations into easy mental compartments in order to understand, analyze and quickly deal with them. It’s a psychological mechanism we all use, almost all the time–no matter our skin color, religion or whatever. Without stereotyping, we would all be asking countless questions to grok everyone and everything in such detail that we’d get no work done and might not even have time to get food!

    It follows logically that we always have to stereotype our readership to some degree. It’s a matter of what degree of detail we have time, budget and attention span to analyze the audience.

    By the way, this would be a good topic to cover in a style guide or publication guidelines.

    Tim Mantylas last blog post..Publication guidelines are more useful than a style guide