home *** CD-ROM | disk | FTP | other *** search
- Newsgroups: comp.lang.c
- Path: sparky!uunet!zaphod.mps.ohio-state.edu!cs.utexas.edu!csc.ti.com!tilde.csc.ti.com!mksol!mccall
- From: mccall@mksol.dseg.ti.com (fred j mccall 575-3539)
- Subject: Re: Giles' Manual Mania (Was - Re: About the 'F' in RTFM)
- Message-ID: <1992Aug17.163058.11643@mksol.dseg.ti.com>
- Organization: Texas Instruments Inc
- References: <1992Jul23.155203.11430@newshost.lanl.gov> <1992Jul26.190928.20817@mksol.dseg.ti.com> <1992Aug4.175921.24917@newshost.lanl.gov> <1992Aug8.015640.11801@cbnews.cb.att.com> <1992Aug10.155255.28139@newshost.lanl.gov> <1992Aug10.161448.1284@newshost.lanl.gov> <1992Aug13.232656.1013@newshost.lanl.gov>
- Date: Mon, 17 Aug 1992 16:30:58 GMT
- Lines: 67
-
- 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.
-