Path: utzoo!utgpu!jarvis.csri.toronto.edu!mailrus!tut.cis.ohio-state.edu!gem.mps.ohio-state.edu!ginosko!aplcen!uakari.primate.wisc.edu!pikes!udenva!isis!scicom!rcw
From: rcw@scicom.AlphaCDC.COM (Robert White)
Newsgroups: comp.software-eng
Subject: Re: Product Documentation
Summary: Write the user manual first
Message-ID: <1893@scicom.AlphaCDC.COM>
Date: 15 Sep 89 08:26:33 GMT
References: <3537@rtech.rtech.com> <6376@hubcap.clemson.edu> <1888@scicom.AlphaCDC.COM> <84091@pyramid.pyramid.com>
Reply-To: rcw@scicom.UUCP (Robert White)
Organization: Mentor Software, Thornton, Co.
Lines: 40


>In article <1888@scicom.AlphaCDC.COM> I write:

++Most companies are unwilling to put what it takes into technical documen-
++They hire inexperienced people who may or may not be technically oriented.
						      ^^^^^^^^^^^^^^^^^^^^
Carl S. Gutekunst responds:  (csg@pyramid.pyramid.com)

>That's rarely the problem. Far more common is that companies hire writers for
>their technical expertise, but don't bother to find out whether they know how
>to *write*. What you end up with is user documentation that looks like it
>written by an engineer who came late into the project.
>
>I can teach someone the technical stuff, if they are willing to learn. But I
>sure can't teach 'em how to write.
>

I think it depends.  My background/bias is in mathematical scientific software.
One of the major failings of the company I used to work with was that they
hired a series of writers who had no background in the science.  This is not
to say they couldn't understand what the software did, but rather they were
unable to communicate with the end user in familiari industry terms.  In
other words, the writing seemed alien.  In the end, I felt so strongly about
this that I wrote my own user guides.

Good writing is 20% talent and 80% hard work.  I still see very few user 
guides that are clear, concise, useful, and helpful.  Even very technical
subjects can be explained clearly given enough effort.  One technique that
seems to be helpful is to write the user guides first.  If a product
is designed well, then it is straightforward to document.  By the same token, 
flaws in the program design such as excessive awkwardness of some procedure
can be corrected early in the design process.  I suppose I am suggesting
integration of documentation into the overall engineering of a project from
its outset.

Yours sincerely,

Robert White (rcw@scicom.alphacdc.com)

in the program design may show early in the process.