I should know better than to get involved in this one…

Sarah O'Keefe / Opinion3 Comments

Kathy Sierra’s Creating Passionate Users blog is one of my favorites. But her latest entry is entitled Why marketing should make the manuals!


Read the whole thing, and then let’s chat. I’ll wait.



Kathy and I do have some points of agreement. For instance:

  • More resources should be allocated to user documentation.
  • Attractive documents are better than ugly documents.

But then, I’m sorry to say that Kathy loses me.

“The brochure gets the big budget while the manual gets the big index.”

Let’s assume that you have a moderately complex product. The index is the most important part of the entire manual. Why? Because readers use the index to find information. If they can’t find it, then from the reader’s point of view, the information doesn’t exist.

Indexes are good. The presence of an index does not mean that you have a big, boring book.

Next, we need to think about different types of documentation and how they are used:

  • Tutorials and quick start guides are intended to be read sequentially and in their entirety. For these, it’s important to hook users, provide them with a reason to keep reading, and make sure that the information is accurate, well-organized, and accessible. These documents, like marketing materials, are intended to persuade and inform.
  • Reference documentation is intended to be read in pieces. The user is doing something with your product. They realize that they don’t have a particular piece of information — can I use an apostrophe in the last name field? They look it up in the reference documentation. Users do not read reference documentation from cover to cover. They dive in, get the information they need, and go back to their work. For reference documentation, it’s critical to provide logical organization and multiple information access techniques (table of contents, index, related topics, alphabetical organization, hyperlinking in online documents, and so on). You can make reference documentation more engaging (for example, you can use entertaining examples), but readers do not want to read the whole thing.
  • User documentation is generally task-oriented; it provides step-by-step instructions on how to complete a particular task. Often, the user documentation includes an introductory chapter that provides a conceptual overview of the product. You definitely want users to read this information. But again, most users will drop in, read about a task or two, and then go back to their work.

There are numerous problems that can arise when you create user documentation:

  • Information is wrong. The information in the user documentation is incorrect; it does not match how the product actually works.
  • Information is missing. The user documentation doesn’t discuss a feature that is present in the product, or provides incomplete information.
  • Information is poorly written. The content is hard to understand. Supporting graphics are non-existent or ugly.
  • Information access is poor. The content is hard to find because the document organization is weird (or absent), the index is poor (or missing), and the page navigation (the book design) doesn’t support scanning for information.
  • Information is ugly. The content is no fun to read because the book design is lacking.

If you had to rank these problems in order, the last bullet would presumably not be at the top of the list. Wrong pretty information is not better than correct ugly information. And this brings us to the crux of the problem. When there aren’t enough resources to create the documentation, the problem list gets triaged, and “make it pretty” is at the bottom of the list. In writing about Kathy’s article, Darren Barefoot said this:

“User manuals get a bad rap because companies don’t devote enough resources to them. That money should be spent on thoughtful tech writers, trainers and support personnel who can make compelling training and support material.” Keep Marketing Away From the Manuals | DarrenBarefoot.com

Investing in making product manuals more attractive is a good thing. But in most documentation groups, there are far more pressing problems that need to be addressed.

Let me also throw in another plug for accessibility. Technical documentation is often repurposed into multiple outputs — print, PDF, HTML, and the like. Design-heavy books tend to be difficult to repurpose and often cause accessibility problems (for example, screen readers don’t much like drop caps).

Finally, it helps to keep in mind that marketing deals with short documents — two-page data sheets, ten-page white papers, brochures, and the like. Technical documentation is orders of magnitude larger — hundred-page documents, thousand-page references. When you are publishing 5,000 pages every six months, it makes sense to consider the efficiency of a particular book design.

About the Author

Sarah O'Keefe


Content strategy consultant and founder of Scriptorium Publishing. Bilingual English-German, voracious reader, water sports, knitting, and college basketball (go Blue Devils!). Aversions to raw tomatoes, eggplant, and checked baggage.

3 Comments on “I should know better than to get involved in this one…”

  1. I think there is a certain assumption that the information provided in manuals should be correct. I also think there is assumption that tools (such as the index) should be present for users so they can get in and get out. What is missing though is an element of passion that can be expressed through documentation with a touch of artistic design.
    This does not mean that single sourcing is not an option or that you must print on glossy paper. It means that the reader has the potential to enjoy the documentation. Take for example PHP.net documentation. One great asset is its comment section that provides code samples and helpful functions along with potential pitfalls. The PHP docs are not pretty but they do inspire in they are full of helpful comments that describe the community behind PHP.
    Marketing is meant to get people interested in using the product and saying that documentation should do the same thing seems like a pretty good idea to me.

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.