Re: Feedback

Subject: Re: Feedback
From: "Robert Plamondon" <robert -at- plamondon -dot- com>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Wed, 16 Jul 2003 09:43:23 -0700

John Posada writes:

>Is it better to include substantial content that's mostly right and mostly
>useful but unreviewed, or is it better to include substantially less
>that is known to be 100% right?

If the benefit to the reader is the criterion, then accuracy on some
information is more critical than others. For example, in a semiconductor
databook, pinout errors result in fried chips and scrapped prototype runs of
boards. Errors that only lead to confusion are more acceptable to readers
than errors that lead to wrecked materials.

Readers can tolerate a certain amount of error and confusion, especially if
the top-level description of the product is complete and helpful.
Documentation that leads to a thorough understanding of the task at hand
allows the reader to discover flaws on his own. Monkey-see, monkey-do
documentation leads him into the dark woods and, if not 100% accurate,
abandons him there.

Whether a reader is better off with something rough-hewn or with nothing at
all depends on the circumstances. Usually, if using the product is not
self-evident, then documentation is called for, and current users should
have the best document currently available. When there is a cost associated
with switching from an old edition to a new one (such as with massive paper
documents or documents that the users typically mark up with their own
notes), the quality benefit should be significantly larger than the cost, or
the users will ignore new editions and continue to use the old ones. With
online documentation, especially Web-based documentation, the costs are low,
and you might as well post stuff when you're pretty sure it's better than
what's there already. Documentation can't help the readers until they can
get their hands on it.

A lot of the perfectionism in the industry is, in my opinion, an artifact of
the high cost of typesetting and printing in the past. Changes were very
expensive, and minimum print runs were large, so scrapping an edition was
almost unthinkable. Now the costs are much lower, and you don't have the
same cost barriers to getting new information out into the field.

Accuracy is not important at all in some kinds of documentation. I would
put "A=A" tautology documentation in this class. A document that tells the
reader nothing but snippets like, "File->Save allows you to save a file"
doesn't need to be accurate, or even to exist (except as a misguided
bureaucratic check-off item). Users will run into two or three tautologies
in a row and never glance at the document again. A document that is never
referred to can do little harm unless it falls on your head during an

-- Robert
Robert Plamondon
President, High-Tech Technical Writing
robert -at- plamondon -dot- com
(541) 453-5841
"We're Looking for a Few Good Clients"


sourcing tool for FrameMaker that lets you easily publish your content
online. No macro language required!

Mercer University's online MS Program in Technical Communication Management:
Preparing leaders of tomorrow's technical communication organizations today.
See or write George Hayhoe at hayhoe_g -at- mercer -dot- edu -dot-

You are currently subscribed to techwr-l as:
archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot- Visit for more resources and info.

Previous by Author: Re: solo writer--how do you keep up, etc?
Next by Author: Re: Work-for-hire question?
Previous by Thread: RE: Getting started as a part-time freelancer
Next by Thread: Learning to code on the cheap

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

Sponsored Ads