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:Re: Sanity check From:"Wing, Michael J" <mjwing -at- INGR -dot- COM> Date:Mon, 26 Aug 1996 17:26:43 -0500
>My feeling about good writing, in help files, and everywhere else in
>product documentation, is that good writing reassures the user that
>product is worthwhile.
I half agree with you. I can see where poor documentation can make a
user think that the product is less worthwhile than it really is, but I
can't completely see it the other way around. IMO, it is the cost,
availability, ease-of-use, compatibility, and functionality that sells
me on the product. If the product does what I want, is available, and
is affordable, then I will suffer with less-than adequate documentation.
However, I may not suffer quietly.
I feel that good writing supplements a good product, but it's the
product itself that reassures the user as to whether it is worthwhile
(unless the user is reading the documentation without having tested the
product). A good document for a poor product is like putting cologne
and a tuxedo on a pig. The user may like the reading, but despite the
good writing, the documentation does nothing to change the user's mind
that the product is still a pig.
However, poor documentation on a good product is a detriment. Unless the
product is very intuitive (and thus, the user can figure out how to
operate it despite the documentation), the documentation can only make
the user think less of the product. IMO, once the user has figured out
the product, they view the product and the documentation as separate
entities. Thus, they may think the product is great if you can figure
out how to use it.
Of course, good documentation with a good product is a win-win
combination and poor documentation on a poor product just plain stinks.
>I think the user makes the subconscious connection
>that, if the documents are error-free, then the product must be
Well, at least up until the time they try to use the product. A
document, no matter how well written, does not add or improve
functionality that is not there to begin with.
>and even more importantly, that if the documents are full of
>errors (even if the errors are grammar or punctuation, rather than
>this product must not be worth a damn.
Maybe, if the document is being used as a Marketing tool. Maybe even
while the user is learning the product. However, once the user is
familiar with the product their opinion of the product may improve while
their opinion of the document probably will not.
>This is the argument I make with those who call me anal-retentive when
>over picky details!
_/ Michael Wing
_/ Principal Technical Writer
_/ Infrastructure Technical Information Development
_/ Intergraph Corporation
_/ Huntsville, Alabama
_/ (205) 730-7250
_/ mjwing -at- ingr -dot- com
TECHWR-L List Information
To send a message about technical communication to 2500+ list readers,
E-mail to TECHWR-L -at- LISTSERV -dot- OKSTATE -dot- EDU -dot- Send administrative commands
ALL other questions or problems concerning the list
should go to the listowner, Eric Ray, at ejray -at- ionet -dot- net -dot-