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: Elegance From:Janice Gelb <janiceg -at- MARVIN -dot- ENG -dot- SUN -dot- COM> Date:Thu, 30 Apr 1998 09:12:17 -0700
Stuart Burnfield wrote:
> It shocked me deeply when Wayne Douglass said:
> > You can't write a manual that's better than the product.
> Then, to make matters worse, Alexia Prendergast said:
> > Couldn't agree with Wayne more on this one
> It's a disturbing feeling to disagree with Wayne (witty, sensible, a
> Unix guy) and Alexia (not a Unix gal, but witty and even more sensible),
> but here goes:
> Aren't you both confusing 'product' with 'software'? The software isn't
> the product. The software, the manual, installation procedure, support,
> and other things all make up the product. Whatever the programmers
> think, customers don't buy software, they buy a product.
> Can the manual be better than the product? It's a meaningless apples-
> and-oranges comparison. Can the manual compensate for deficiencies in
> the software and so make the product better? Yes, isn't that what we
> try to do all the time?
Much as it pains me, I have to say that although we would *like* to
think that the quality of documentation and support is an important
factor in why customers buy a product, I think the real reason is that
they need to do a job that the software enables them to do. Even if the
manual or the support are bad, they will buy the software anyway if
they need the capabilities it provides. Of course, if they have a
choice between two equal products, one with great support and
documentation and one with bad, they will obviously choose the former,
but there rarely are two software products that are so equal, assuming
there is any competition in the area at all!
If the software is inconsistent and confusing to use, a great manual
describing it is not going to make the product consistent, easy to
learn and easy to use. It may explain the inconsistencies and try to
dispel the confusion, but the writer can only do that up to a point.
And the manual itself will not be as well organized or concise if
the software is inconsistent, since there is no way to succinctly
Even as a person in the technical communication field, if I had to
choose between elegant, consistent, easy-to-use software with crummy
documentation and confusing, inconsistent, difficult-to-learn software
with great documentation, I'd definitely choose the former.
Janice Gelb | The only connection Sun has with this
janice -dot- gelb -at- eng -dot- sun -dot- com | message is the return address. http://www.geocities.com/Area51/8018/index.html
"The Web is the world's greatest library with all the books on the floor"
-- Patrick Casey, AP (Oklahoma)