Marketing/propaganda in documentation

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.

Steven J. Owens
uso01 -at- unidata -dot- com

Previous by Author: FrameMaker 3.x.x
Next by Author: Alternative to FRAMEViewer
Previous by Thread: Humour: Nocilis of Yppolf #3
Next by Thread: Marketing/propaganda in documentation

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

Sponsored Ads