Random thoughts about publishing

icon Site Feed


Palimpsest has moved. Please visit our blog in its new location for the most recent posts from Scriptorium.



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

Thursday, August 31, 2006 — posted by Sarah

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:
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:
There are numerous problems that can arise when you create user documentation:
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.
1:07 PM Permalink | |

<< Home


Scriptorium Publishing | Post Office Box 12761 Research Triangle Park, NC 27709 | (919) 481 2701 | info@scriptorium.com