Boring documentation?

Subject: Boring documentation?
From: Geoff Hart <ghart -at- videotron -dot- ca>
To: TECHWR-L <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Wed, 22 Mar 2006 11:17:11 -0500

It pays to take a step back and remind ourselves of why people consult our documentation: the vast majority are not doing it for the pleasure of reading, and pretending that they are can lead us astray.

Most people turn to the docs for one reason only, and only when they absolutely have to do so: to help them solve a problem or accomplish something. When they do, they may be highly stressed (e.g., the software crashed or they're under time pressure), frustrated (e.g., the software refuses to do what they're convinced it should do when they act in a certain way), angry (e.g., the software doesn't work the way the docs say it should), etc. They are emphatically not curling up by the fire to read the docs the same way they'd read a novel. _Of course_ the documentation is boring: there are no characters, jokes, or plotlines, and the graphics are uninteresting (it's not a comic book).

The obvious exception is documentation for things such as games that are used for relaxation or pleasure. There, it pays to be entertaining because that's part of the audience context. But even then, you have to clearly distinguish between the body of the docs, which can be amusing or absorbing, and the "something bad just happened and I need to fix it" parts. The latter must be deadly dull and serious, since I've seen many people go ballistic when they are stressed and read what appears to be disrespectful or facetious writing.

Can a hybrid approach (less boring) work? The "For Dummies" books prove that it can--for a very narrowly defined audience. The fact that these books sell in the millions tells us that documentation _can_ be more exciting than a telephone directory. However, the fact that a goodly number of techwhirlers in this list recently reported being annoyed by these books and feeling patronized is also clear evidence that there are risks in taking this approach.

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - --
Geoff Hart ghart -at- videotron -dot- ca
(try geoffhart -at- mac -dot- com if you don't get a reply)
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -


WebWorks ePublisher Pro for Word features support for every major Help
format plus PDF, HTML and more. Flexible, precise, and efficient content delivery. Try it today!.
Doc-To-Help includes a one-click RoboHelp project converter. It's that easy. Watch the demo at

You are currently subscribed to TECHWR-L as archive -at- infoinfocus -dot- com -dot-
To unsubscribe send a blank email to techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
or visit

To subscribe, send a blank email to techwr-l-join -at- lists -dot- techwr-l -dot- com

Send administrative questions to lisa -at- techwr-l -dot- com -dot- Visit for more resources and info.


RE: Rhetoric And Technical Writing?: From: Steven Brown

Previous by Author: Finding character styles in Word with VBA?
Next by Author: Avoiding "Uninstallation"?
Previous by Thread: RE: Rhetoric And Technical Writing?
Next by Thread: Re: Boring documentation?

What this post helpful? Share it with friends and colleagues:

Sponsored Ads