From: mccall@mksol.dseg.ti.com (fred j mccall 575-3539)
Subject: Re: Giles' Manual Mania (Was - Re: About the 'F' in RTFM)
Organization: Texas Instruments Inc
Date: Mon, 17 Aug 1992 16:30:58 GMT

In <1992Aug13.232656.1013@newshost.lanl.gov> jlg@cochiti.lanl.gov (Jim Giles) writes:

>In article <1992Aug13.175711.27749@mksol.dseg.ti.com>, mccall@mksol.dseg.ti.com (fred j mccall 575-3539) writes:
>|> [...]
>|> >Second, what it's supposed to do often doesn't match what it does.  
>|> 
>|> Then you REALLY have a problem.  If you have a sine routine and it
>|> computes tangent instead, I'd say that more than the documentation is
>|> broken.  I've found that a lot of the time when people come to me and
>|> say "This doesn't do what the documentation says it does", the real
>|> problem is that they've misread the documentation.

>Six of one ....  Whether the document is misunderstood or whether it's
>wrong, it's badly written - and that's the major problem.  If a document
>is persistently misread, then it's just as wrong as if it contained false
>information.

This is not necessarily true.  It's rather like saying that the fact
that we continue to have any automobile accidents at all is evidence
that roadways and automobiles are badly designed.  No matter what you
do, you can't protect the really bad driver from him/herself.
Similarly, no matter what you do with the documentation set, you
cannot protect the poor, inattentive, or lazy reader from misreading
it. 

>In any case, this is my final word on the subject of manual quality:

>   Given a set of documents on one hand and a friendly guru (who is willing 
>   to answer all questions with no insults and without saying RTFM) on the
>   other hand, if the average user *chooses* to read the document, then the 
>   documentation is well written.  I will adopt that as my definition of 
>   "well written".

This is more a measure of document size than anything else, I would
suspect.  In any case, I don't think it's a workable definition.

>I've used software products where the bulk of the users *preferred* to
>obtain and read the documents rather than asking the consultants.  I know
>this is a possible way to write software/documents.  

I'm curious.  What products are these, and just what is this
miraculous difference in the documentation?  By making the
documenation sufficiently simplistic and doing the same with the user
interface, this can certainly be achieved.  However, then you have the
problem of the total inability to accomplish what you need to
accomplish because you have a wall of cotton between you and the
environment. 

>Admittedly, most 
>commercial and/or public domain software is not documented in this way.
>UNIX documents are worse than most - they remind me a lot of OS/360
>manuals in the way you have to dig through them to get the information 
>you need.  The OS/360 stuff was like that through over-organization, and
>the UNIX stuff through under-organization.  And BOTH describe user 
>environments which are filled with niggly little arcane "gotchas"
>that would be hard for anyone to document.

I thought you were just complaining about AT&T.  If you make the
environment sufficiently 'non-powerful', all those niggly little
"gotchas" go away.  I prefer to be able to get things done.


-- 
"Insisting on perfect safety is for people who don't have the balls to live
 in the real world."   -- Mary Shafer, NASA Ames Dryden
------------------------------------------------------------------------------
Fred.McCall@dseg.ti.com - I don't speak for others and they don't speak for me.
Newsgroups: comp.lang.c