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

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

Ugh.

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

Ready?

So.

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.