Path: utzoo!attcan!uunet!cs.utexas.edu!mailrus!sharkey!mcf!mibte!gamma!towernet!pyuxp!pyuxe!nvuxr!jgn
From: jgn@nvuxr.UUCP (Joe Niederberger)
Newsgroups: comp.software-eng
Subject: Re: Product Documentation (Was: Are users stupid?)
Message-ID: <1312@nvuxr.UUCP>
Date: 20 Sep 89 14:22:26 GMT
References: <1596@mks.UUCP>
Reply-To: jgn@nvuxr.UUCP (22143-Joe Niederberger)
Organization: Bell Communications Research
Lines: 27


>(a)  Writers may be hired on the basis of confused criteria.  For
>     example, IBM in Toronto had trouble hiring technical writers.

I always thought that IBM had the very finest technical writers (do I
*need* a smiley here?) For example, I liked this quote so much I had in
done in caligraphy and framed:

   "For the logical parent to physical parent path, the user controls
the sequence in which occurances of the real logical child are accessed
from their logical parent by defining a virtual logical child segment
type as a physical child of the logical parent of the real logical
child, and in addition, by defining a sequence field in the virtual
logical child." 

4.58 IMS/VS System/Application Design Guide

Now, whose fault is it that this blurb is nearly indecipherable ? Is it
the poor writer, or the IMS guru who coined such memorable terms as
"virtual logical child segment type" and "real logical child" ?? I see
the same thing happening today where everything is "object this" and
"object that." I contend that much of the difficulty in writing coherent
technical documentation is the poor choice of terminology, which is
generated, not by technical writers, but by the very creators of the
technology in question.

Joe Niederberger