Re: Five Point Quality Test

[Len Olszewski <saslpo -at- UNX -dot- SAS -dot- COM>]

Charles Fisher responds to my posting about programmers as an audience:

> If you can produce a document for your primary audience that meets their
> needs and exceeds their expectations, then I argue that you have produced
> a high quality document. Although we (as technical writers) may have
> our own ideas about what makes up a 'quality' document, the audience for
> the document must be the final judge. Aside from research-proven techniques
> of writing to improve clarity, comprehension, and readability, everything
> else in a document is 'up for grabs,' so to speak.

> The $100 million powerball question, then, is this: What are your
> audience's needs and expectations? The only way to get an answer to that
> question is to ask it to your audience.


Charles,

You and I are in agreement, up to a point. If your audience expects
tripe because that is what it is used to receiving, and asks you to
amend your document so it *too* is tripe, I think you do them a
disservice to comply with their wishes.

In the example I cited originally, I was not *about* to convert all of
my verb constructions to the passive voice, even though one reviewer
(thankfully, only one, a programmer) suggested it.  Since he's seen more
of my stuff since then, he hasn't made that suggestion again.

Asking your audience for its needs and expectations is, without
question, the best way to find out what your readers want. That doesn't
mean you lurch from technique to technique at its whim, nor that your
own ideas about quality documentation are necessarily wrong. A lot
depends on how good your material is to start, how you figure out who to
ask, and what you ask. Often, research can also provide contradictory
results, sometimes indicating your audience is neither homogeneous nor
in agreement with itself regarding its needs and expectations.

But, I know about the contributions that an active and engaged usability
testing program can make to a product *and* its documentation. I also
know that conventional wisdom is often incorrect. It's hard to let go of
certain ideas based on research, but you are right in suggesting that is
the way to go, IMHO of course.

|Len Olszewski, Technical Writer |"You can observe a lot by watching."|
|saslpo -at- unx -dot- sas -dot- com|Cary, NC, USA|     - Yogi Berra                   |
|---------------------------------------------------------------------|
| Opinions this ludicrous are mine. Reasonable opinions will cost you.|