Xref: utzoo comp.sys.pyramid:585 comp.software-eng:1955
Path: utzoo!attcan!utgpu!jarvis.csri.toronto.edu!mailrus!ames!ncar!ico!isis!scicom!rcw
From: rcw@scicom.AlphaCDC.COM (Robert White)
Newsgroups: comp.sys.pyramid,comp.software-eng
Subject: Re: Product Documentation (Was: Are users stupid?)
Message-ID: <1888@scicom.AlphaCDC.COM>
Date: 9 Sep 89 05:57:12 GMT
References: <3537@rtech.rtech.com> <6376@hubcap.clemson.edu>
Reply-To: rcw@scicom.UUCP (Robert White)
Organization: Mentor Software, Thornton, Co.
Lines: 36

In article <6376@hubcap.clemson.edu> billwolf%hazel.cs.clemson.edu@hubcap.clemson.edu writes:
>From markd@salmon.rtech.com (Mark P. Diamond):
>    [good story on the faulty washing machine documentation deleted]

>
>    Most software engineers understand completely the need to define
>    variables before using them; why do technical writers not understand
>    the need to define precisely what is to be manipulated and precisely
>    how to go about manipulating it, for each possible user action???

Several reasons.  Most companies are unwilling to put what it takes into
technical documentation.  They hire inexperienced people who may or may
not be technically oriented.  I think a willingness to "play user" with
the product that is to be documented is a prerequisite.
You also must be willing to learn everything there is to know about the
product.

You can't be good at technical writing until you have written some,
issued it, interacted with end users, revised it, and issued it again.
You also can't write well unless you use the product in a real life 
situation.  That's a problem shared with test
data as well.  The parameters of the user application must be
understood to write decent manuals.


>    Bill Wolfe, wtwolfe@hubcap.clemson.edu

I can't find it right now, but there is a book with a title something
like "The Design of Everday Things" containing excellent discussions 
on the design (or lack thereof) of everything from hot/cold taps to
computer software.  For example, if taps are arranged vertically, how
do you know which is hot and which is not?  Highly recommended.  I will
try to find the author and title if someone else does not beat me to it.

Robert White
rcw@scicom.alphacdc.com