home *** CD-ROM | disk | FTP | other *** search
/ NetNews Usenet Archive 1992 #18 / NN_1992_18.iso / spool / comp / lang / c / 12300 < prev    next >
Encoding:
Internet Message Format  |  1992-08-13  |  2.5 KB
  1. Path: sparky!uunet!cs.utexas.edu!swrinde!sdd.hp.com!uakari.primate.wisc.edu!caen!hellgate.utah.edu!lanl!cochiti.lanl.gov!jlg
  2. From: jlg@cochiti.lanl.gov (Jim Giles)
  3. Newsgroups: comp.lang.c
  4. Subject: Re: Giles' Manual Mania (Was - Re: About the 'F' in RTFM)
  5. Message-ID: <1992Aug13.232656.1013@newshost.lanl.gov>
  6. Date: 13 Aug 92 23:26:56 GMT
  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>
  8. Sender: news@newshost.lanl.gov
  9. Organization: Los Alamos National Laboratory
  10. Lines: 36
  11.  
  12. In article <1992Aug13.175711.27749@mksol.dseg.ti.com>, mccall@mksol.dseg.ti.com (fred j mccall 575-3539) writes:
  13. |> [...]
  14. |> >Second, what it's supposed to do often doesn't match what it does.  
  15. |> 
  16. |> Then you REALLY have a problem.  If you have a sine routine and it
  17. |> computes tangent instead, I'd say that more than the documentation is
  18. |> broken.  I've found that a lot of the time when people come to me and
  19. |> say "This doesn't do what the documentation says it does", the real
  20. |> problem is that they've misread the documentation.
  21.  
  22. Six of one ....  Whether the document is misunderstood or whether it's
  23. wrong, it's badly written - and that's the major problem.  If a document
  24. is persistently misread, then it's just as wrong as if it contained false
  25. information.
  26.  
  27. In any case, this is my final word on the subject of manual quality:
  28.  
  29.    Given a set of documents on one hand and a friendly guru (who is willing 
  30.    to answer all questions with no insults and without saying RTFM) on the
  31.    other hand, if the average user *chooses* to read the document, then the 
  32.    documentation is well written.  I will adopt that as my definition of 
  33.    "well written".
  34.  
  35. I've used software products where the bulk of the users *preferred* to
  36. obtain and read the documents rather than asking the consultants.  I know
  37. this is a possible way to write software/documents.  Admittedly, most 
  38. commercial and/or public domain software is not documented in this way.
  39. UNIX documents are worse than most - they remind me a lot of OS/360
  40. manuals in the way you have to dig through them to get the information 
  41. you need.  The OS/360 stuff was like that through over-organization, and
  42. the UNIX stuff through under-organization.  And BOTH describe user 
  43. environments which are filled with niggly little arcane "gotchas"
  44. that would be hard for anyone to document.
  45.  
  46. -- 
  47. J. Giles
  48.