Marketing-slime in user doc

[HOLLAND -at- IPFWCVAX -dot- BITNET]

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.

        Steve Hollander
        holland -at- cvax -dot- ipfw -dot- indiana -dot- edu