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/propaganda in documentation From:Steve Owens <uso01%eagle -at- UNIDATA -dot- COM> Date:Mon, 17 Jan 1994 10:22:45 +0700
> The latest version of an operator's guide I'm working on with 3 other
> people contains a chapter, close to the beginning, whose title is the
> company slogan and is written as though the customer still had to be
> convinced to purchase the product. It contains useful information, but
> the info:hype ratio is distressingly low.
This is bad. I usually try to avoid this kind of thing completely,
rather than have to deal with it, but when I do have to deal with it, I use
a straightforward usability test. Does it get in the user's way?
1) Does this directly further the user's purpose (using the program)?
2) Does this indirectly further the user's purpose (...)?
3) Is this harmless?
4) Does this do nothing, but still gets in the way?
5) Does this actively interfere with the user's purpose (...)?
If it's direct task knowledge, it belongs there.
If it's related task knowledge (for example, abstract
information that gives the user a feel for how/why the program
functions) then it should be handled carefully to keep things on
track, but it still has a purpose.
If it's not too useful in either sense, but could be useful
and is short enough and well-marked to allow the user to skip over it
if need be, then it may be left in, but it's something to think about.
If it's not useful, then it doesn't belong there - even if
it's harmless, it'll probably get in the way, waste the user's time,
throw the user off track, and if nothing else, cost you an extra page
in the printing costs :-)
And, of course, it may contribute to confusing, misleading, or
delaying the user (which will only anger the user, interfering with the
learning process).
Of course, a lot of factors have to be taken into account to
determine exactly what benefits, if any, that portion of the text
"buys" you. If it's a very friendly piece, chatty in nature (e.g.
"Life With UNIX" or "Peter Norton's Guide To UNIX") then occasional
forays into anecdote or side-comments actually contribute to
maintaining the reader's interest, even if they fail to provide
anything on a factual basis.
