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.
Patrick O'connell writes:===============================================
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
I have a BIG problem with this. I can see where this kind of tool is useful;
it's not that I object to its creation. I simply feel it has no place in user
documentation -- it should be in a marketing pamphlet or something. If the
customer has already purchased product X, I'm afraid s/he will react
negatively to finding anOTHER sales job awaiting him/her when they crack the
I've posted on TECHWR-L pressing for recognition that the User's Manual,
like all documentation, is a marketing tool as well as an informational
tool. The marketing in a User's Manual, however, is conveyed in the
way it makes the user feel comfortable with the application, and makes
the user think "hey, this really *is* easy/useful!"
Often the first chapter in the manual can be used as a "marketing tool"
in that it details the most useful features or the latest additions
to the program. This is also useful to the user--the new user may
see ways to use the program he or she never thought of, and feel even
better about the purchase. The old users who are upgrading are going to
appreciate the fact that they don't have to wade through the whole
manual to figure out what's new.
It sounds like in this case that there's a lot of extra hyperbole in
there, singing the praises of the program without providing specific,
useful details for the reader. In this case, you're probably right--
it's wasted space that probably does more to undermine the user's
confidence in the product.
A general rule of thumb for this type of introduction is:
Does it help the user understand and use this product more quickly?
If it does, then leave it in. Does it give unnecessary information
or merely boost the program without specific details? Leave it out.
The style of the writing is, in truth, a secondary consideration. Keep
the user's needs in mind, and you'll refrain from the mindless hyperbole
that detracts from a product's image instead of building it.
Naturally, this is all IMHO.
Anatole Wilson "If I should say to a novice,
Sr. Assoc. Information Developer 'write from experience only,'
IBM, Santa Teresa Labs I should feel that this was
awilson -at- vnet -dot- ibm -dot- com rather a tantalizing monition
if I were not careful to add,
'try to be one of the people
on whom nothing is lost.'"
all company disclaimers apply --Henry James