[comp.software-eng] Product Documentation

billwolf%hazel.cs.clemson.edu@hubcap.clemson.edu (William Thomas Wolfe,2847,) (09/03/89)

From markd@salmon.rtech.com (Mark P. Diamond):
> if this is my first time using a computer, how do I know that the 
> power comes from the outlet, and not say the bridge lines, cabling 
> or other wires?  Obvious?  My telephone doesn't have an AC plug.  [...]

    An excellent point.  Another example: I just came from a laundromat
    at which I encountered two gentlemen from a foreign country, who had
    considerable difficulty figuring out how to operate the washers and
    dryers.  Both of them spoke excellent English, and both seemed quite
    intelligent, but the directions printed on the washer were NOT clear.

    Their primary problem was that the washer directed them to insert their
    coins into the slots (not bothering to specify the precise type of coin,
    of course), and then failed to tell them that they had to push the coin
    holder in and then pull it back out again.  They waited for a while for
    the washer to start, but to no avail.  

    Whose fault was this?  Not the user's... this was totally a result of 
    inadequate user documentation, caused by a failure on the part of the
    technical writer to identify and describe all relevant actions.

    Here's another example: automobile owner's manuals frequently specify
    that one is to change the oil periodically, but manage to avoid any
    indication of where one is to put the oil in after draining out the
    old oil.  Since there are quite a few caps on the engine, the question
    of which one to pour the oil into is nontrivial.  The failure of the
    owner's manual would not be fatal if the caps were labeled with letters
    like "OIL", and indeed letters are placed on practically everything on 
    the engine which indicate obscure part numbers, etc.  But there is 
    absolutely NO lettering which is designed to help the user figure out
    which cap is associated with which fluid!!!

    Once again... a very poorly documented product.

    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???

> What I am really arguing against is the arrogance of engineers who can't
> design real systems for real people to use, and the arrogance of service
> people who believe their time too precious to waste on "stupid" people.  
> Maybe, just maybe the system you designed Mr. Engineer isn't as easy to use 
> or install or fix or whatever as you think.  Don't pass the buck onto me 
> for being stupid.  Or worse, if I the user haven't mentally put all the 
> pieces together, if I'm having a bad day and my boss is pushing me to get 
> this system online and I run into what I think is a problem, and I call you
> Mr. Field Sevice Person, don't treat me like an idiot.  Help me solve
> our problem.

    Precisely.  


    Bill Wolfe, wtwolfe@hubcap.clemson.edu

rcw@scicom.AlphaCDC.COM (Robert White) (09/09/89)

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

eugene@eos.UUCP (Eugene Miya) (09/10/89)

In article <1888@scicom.AlphaCDC.COM> rcw@scicom.UUCP (Robert White) writes:
>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.

That's The Psychology of Everyday Things (POET) by Don Norman UCSD
(dnorman@ucsd.edu).  A moderately pleasant antecodotal book bashing
"form over functionality" [my words].  Would be nice if it went further.

Another gross generalization from

--eugene miya, NASA Ames Research Center, eugene@aurora.arc.nasa.gov
  resident cynic at the Rock of Ages Home for Retired Hackers:
  "You trust the `reply' command with all those different mailers out there?"
  "If my mail does not reach you, please accept my apology."
  {ncar,decwrl,hplabs,uunet}!ames!eugene
  				Live free or die.

sommar@enea.se (Erland Sommarskog) (09/11/89)

Robert White (rcw@scicom.UUCP) writes:
>For example, if taps are arranged vertically, how
>do you know which is hot and which is not?

I haven't been confronted with vertical tap arrangements,
but I have been to places where hot tap was the one to
the right.
-- 
Erland Sommarskog - ENEA Data, Stockholm - sommar@enea.se

csg@pyramid.pyramid.com (Carl S. Gutekunst) (09/12/89)

In article <1888@scicom.AlphaCDC.COM> rcw@scicom.UUCP (Robert White) writes:
>Most companies are unwilling to put what it takes into technical documen-
>tation.

True....

>They hire inexperienced people who may or may not be technically oriented.
						      ^^^^^^^^^^^^^^^^^^^^
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.

Followups to comp.software-eng only.

<csg>

jim@mks.UUCP (Jim Gardner) (09/12/89)

[...]

Why is so much documentation bad?  I have been a technical writer
for ten years, have done a lot of freelancing for different companies,
and have a few ideas of things that can go wrong.

(a)  Writers may be hired on the basis of confused criteria.  For
     example, IBM in Toronto had trouble hiring technical writers.
     Therefore they hired a number of people who had applied for
     programming jobs, and promised those people they would be allowed
     to transfer to programming after they built up a little seniority.
     Clearly, these people didn't want to *be* writers, nor would they
     have any feeling for the job.  How could anyone expect them to
     put full effort into what they were doing?  (We will ignore the
     question of how qualified any of these people were to write for
     a living.)

(b)  Technical writers are frequently supervised by programmers.
     Programmers often have the innate belief that the features
     which were hardest to implement must require the most
     documentation.  In many cases, of course, the details of
     the implementation have nothing to do with what the documentation
     should say...but try to convince the programmer of that.

(c)  Companies often have no idea of what they want their documentation
     to do.  When I begin to write any documentation, one of my first
     questions is, "Who do you think is going to read this?"  Software
     documentation should be aimed at the needs of the user...but many
     software vendors have no idea of who the user is going to be.
     There is a vast difference between what a novice wants to see
     and what an experienced user wants to see, but companies often
     do not know who their audience is going to be.

(d)  Production of software tends to dominate production of
     documentation in the eyes of many companies.  For example, the
     scheduling for distributing a package may be entirely keyed to
     the readiness of the software, not the documentation; the second
     that the software is ready, the company wants the package out
     the door.  This means that the documentation must be prepared
     before the software has been finished (before the testing is
     finished at any rate).  There have been many times that I have
     found myself documenting features that don't work yet.  I am
     blithely suggesting that the user try certain commands as
     examples, when *I* can't try those examples to see if they work.

I am happy to say that my current employers have more enlightened
attitudes to the documentation process.  Nevertheless, I've seen
how slap-dash some companies are and bush-league documentation never
comes as a surprise to me.

		Jim Gardner, Mortice Kern Systems

mikeh@dell.dell.com (Mike Hammel) (09/13/89)

In article <1596@mks.UUCP> jim@mks.UUCP (Jim Gardner) writes:
[...]
-     the door.  This means that the documentation must be prepared
-     before the software has been finished (before the testing is
                                             ---------------------
-     finished at any rate).  There have been many times that I have
      --------           
Don't I know it.  In previous work I developed test plans and testcase
suites from internal documentation, ie the stuff the designers wrote     
themselves.  Lately I work more with external documentation, manuals and
such that come from outside vendors.  In both cases I've had to work with
incomplete and incorrect information.  Try determining how to test         
compatibility or functionality when the folks who designed the thing don't
know what its supposed to do!  The "dream" scenario for me would be to have
design documents finished before the product gets to the test group, or in
the case of outside vendor materials, have user documents that are up to date
with the version/release that is received for testing.  Unfortunately this 
seldom happens (at least for me).  

No wonder it seems like the test group is always holding up the product. :-)
(We test engineers know better, though.)

Michael J. Hammel
Dell Computer Corp.

rcw@scicom.AlphaCDC.COM (Robert White) (09/15/89)

>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.

jgn@nvuxr.UUCP (Joe Niederberger) (09/20/89)

>(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