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.
Subject:Marketing-slime in user doc From:HOLLAND -at- IPFWCVAX -dot- BITNET Date:Mon, 17 Jan 1994 18:35:16 EST
In a recent response, Dave Venzke noted that he has "no problem including
[marketing info] in user documentation, especially if it's all in a separate
introductory chapter that the end-user can choose to skip over if s/he
chooses." Ouch: If the introduction to a document proves skippable, the
3% of users who actually RTFM are, IMHO, likely to conclude that the rest is,
too. An analogy (and, yes, my logic prof taught me not to argue by analogy):
A set of instructions which begins with the admonition that the reader review
all 276 steps before beginning Step 1 is likely to induce errors, since
readers will already have concluded that it's okay to play fast and loose with
the instructions. If they skip Step 1: Read the next 72 pages before you
start--they'll skip other unpleasantnesses, too.
The journalist in me also argues against an introductory chapter devoted to
information of questionable usefulness to readers: The "lead" to a manual
ought to contain its central who-what-when-where-why thingies; it ought to
be a grabber so powerful that readers'll _want_ to read the rest of the thing
in hopes it'll be equally interesting/useful.
Yes, sophisticated would-be buyers often examine the documentation before
making a purchasing decision. But an increasing number of these people also
have the sophistication to see when they're being hyped.
holland -at- cvax -dot- ipfw -dot- indiana -dot- edu