TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
>Is it better to include substantial content that's mostly right and mostly
>useful but unreviewed, or is it better to include substantially less
content
>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
earthquake.
NEED TO PUBLISH FRAMEMAKER CONTENT ONLINE? "Mustang" is a NEW single
sourcing tool for FrameMaker that lets you easily publish your content
online. No macro language required! http://www.ehelp.com/techwr-l3
Mercer University's online MS Program in Technical Communication Management:
Preparing leaders of tomorrow's technical communication organizations today.
See www.mercer.edu/mstco 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 http://www.raycomm.com/techwhirl/ for more resources and info.
