Enormous Introductions

Subject: Enormous Introductions
From: Robert Plamondon <robert -at- PLAMONDON -dot- COM>
Date: Wed, 2 Oct 1996 06:30:40 PDT

Moshe described a situation where a manager insisted on expanding
an introduction into a theoretical tome. I have run into the same
thing. It seems to resolve around a cognitive flaw. Some people
feel uneasy when a statement in the introduction does not contain
the entire truth, and want to pour in a more complete description
and enumerate all the exceptions.

Thus, the page-one bullet item that introduces the feature that is
discussed in chapter 3 expands until is becomes a second copy of chapter 3.

At this point, the cognitively-impaired reviewer will worry that the
first paragraph of chapter 3 does not contain all the material in the
subsequent 37 pages.

There are several ways of dealing with such people. Killing them
is the most satisfying, but is hard on the carpets. Actively hiding
introductory material from them is better. Once they complain, simply
rip out the introductory material, leaving them with a big, fat,
technical first chapter. They will be happy. Have people whose
minds do not slag down when presented with introductory material review
the introductory material. Get some review comments to the effect that
introductory material is necessary, then slap it back in at the last

You can do this without being sneaky at all. Simply divide the
manual up into chunks, and give different chunks to different reviewers.
Few people will complain about having to review only the stuff that
they're particularly expert in.

-- Robert
Robert Plamondon, President/Managing Editor, High-Tech Technical Writing, Inc.
36475 Norton Creek Road * Blodgett * Oregon * 97326
robert -at- plamondon -dot- com * (541) 453-5841 * Fax: (541) 453-4139

Previous by Author: Re: Are UNIX manpages obsolete?
Next by Author: Re: Are UNIX manpages obsolete?
Previous by Thread: Since/Because and Which/That
Next by Thread: Re: Tech writers' salaries

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

Sponsored Ads