home *** CD-ROM | disk | FTP | other *** search
/ NetNews Usenet Archive 1992 #18 / NN_1992_18.iso / spool / comp / lang / c / 12427 < prev    next >
Encoding:
Text File  |  1992-08-17  |  4.0 KB  |  78 lines

  1. Newsgroups: comp.lang.c
  2. Path: sparky!uunet!zaphod.mps.ohio-state.edu!cs.utexas.edu!csc.ti.com!tilde.csc.ti.com!mksol!mccall
  3. From: mccall@mksol.dseg.ti.com (fred j mccall 575-3539)
  4. Subject: Re: Giles' Manual Mania (Was - Re: About the 'F' in RTFM)
  5. Message-ID: <1992Aug17.163058.11643@mksol.dseg.ti.com>
  6. Organization: Texas Instruments Inc
  7. 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>
  8. Date: Mon, 17 Aug 1992 16:30:58 GMT
  9. Lines: 67
  10.  
  11. In <1992Aug13.232656.1013@newshost.lanl.gov> jlg@cochiti.lanl.gov (Jim Giles) writes:
  12.  
  13. >In article <1992Aug13.175711.27749@mksol.dseg.ti.com>, mccall@mksol.dseg.ti.com (fred j mccall 575-3539) writes:
  14. >|> [...]
  15. >|> >Second, what it's supposed to do often doesn't match what it does.  
  16. >|> 
  17. >|> Then you REALLY have a problem.  If you have a sine routine and it
  18. >|> computes tangent instead, I'd say that more than the documentation is
  19. >|> broken.  I've found that a lot of the time when people come to me and
  20. >|> say "This doesn't do what the documentation says it does", the real
  21. >|> problem is that they've misread the documentation.
  22.  
  23. >Six of one ....  Whether the document is misunderstood or whether it's
  24. >wrong, it's badly written - and that's the major problem.  If a document
  25. >is persistently misread, then it's just as wrong as if it contained false
  26. >information.
  27.  
  28. This is not necessarily true.  It's rather like saying that the fact
  29. that we continue to have any automobile accidents at all is evidence
  30. that roadways and automobiles are badly designed.  No matter what you
  31. do, you can't protect the really bad driver from him/herself.
  32. Similarly, no matter what you do with the documentation set, you
  33. cannot protect the poor, inattentive, or lazy reader from misreading
  34. it. 
  35.  
  36. >In any case, this is my final word on the subject of manual quality:
  37.  
  38. >   Given a set of documents on one hand and a friendly guru (who is willing 
  39. >   to answer all questions with no insults and without saying RTFM) on the
  40. >   other hand, if the average user *chooses* to read the document, then the 
  41. >   documentation is well written.  I will adopt that as my definition of 
  42. >   "well written".
  43.  
  44. This is more a measure of document size than anything else, I would
  45. suspect.  In any case, I don't think it's a workable definition.
  46.  
  47. >I've used software products where the bulk of the users *preferred* to
  48. >obtain and read the documents rather than asking the consultants.  I know
  49. >this is a possible way to write software/documents.  
  50.  
  51. I'm curious.  What products are these, and just what is this
  52. miraculous difference in the documentation?  By making the
  53. documenation sufficiently simplistic and doing the same with the user
  54. interface, this can certainly be achieved.  However, then you have the
  55. problem of the total inability to accomplish what you need to
  56. accomplish because you have a wall of cotton between you and the
  57. environment. 
  58.  
  59. >Admittedly, most 
  60. >commercial and/or public domain software is not documented in this way.
  61. >UNIX documents are worse than most - they remind me a lot of OS/360
  62. >manuals in the way you have to dig through them to get the information 
  63. >you need.  The OS/360 stuff was like that through over-organization, and
  64. >the UNIX stuff through under-organization.  And BOTH describe user 
  65. >environments which are filled with niggly little arcane "gotchas"
  66. >that would be hard for anyone to document.
  67.  
  68. I thought you were just complaining about AT&T.  If you make the
  69. environment sufficiently 'non-powerful', all those niggly little
  70. "gotchas" go away.  I prefer to be able to get things done.
  71.  
  72.  
  73. -- 
  74. "Insisting on perfect safety is for people who don't have the balls to live
  75.  in the real world."   -- Mary Shafer, NASA Ames Dryden
  76. ------------------------------------------------------------------------------
  77. Fred.McCall@dseg.ti.com - I don't speak for others and they don't speak for me.
  78.