Return to BSD News archive
Path: sserve!newshost.anu.edu.au!harbinger.cc.monash.edu.au!simtel!zombie.ncsc.mil!news.mathworks.com!panix!bloom-beacon.mit.edu!boulder!junco.fsl.noaa.gov!kelly From: kelly@junco.fsl.noaa.gov (Sean Kelly) Newsgroups: comp.unix.bsd.freebsd.misc Subject: Re: Documentation project (was Re: Slight flame from Linux user) Date: 17 Jun 1995 15:19:28 GMT Organization: Forecast Systems Laboratory Lines: 30 Message-ID: <3rurq0$eai@CUBoulder.Colorado.EDU> References: <3ql3gd$je2@bell.maths.tcd.ie> <3rnmjc$fde@bell.maths.tcd.ie> <3roj57$l5s@pandora.sdsu.edu> <3rqdbg$q1u@hamilton.maths.tcd.ie> NNTP-Posting-Host: junco.fsl.noaa.gov In article <3rqdbg$q1u@hamilton.maths.tcd.ie>, Timothy Murphy <tim@maths.tcd.ie> wrote: >>but having sections of documentation written by different >>authors could not lead to a good manual. Is that reasonable? > >I don't know whether it is reasonable, but I am sure it is true. >A manual in which each chapter (even each section) is written by a >different author is most unlikely to be readable. You just have no idea how collaborative writing works. Please find some manuals that you find to be of good quality and then contact the publishers/companies that produced them. I'll think you'll be surprised how many writers, editors, and document specialists worked on each one ... I'll wager the total will be higher than one. Then, read a copy of Edmond Weiss's _How to Write a Usable User Manual_. You'll be surprised (again) how much his method resembles software construction. I also recommend Jonathan Price's _How to Write a Computer Manual: A Handbook of Software Documentation_. -- Sean Kelly NOAA Forecast Systems Lab, Boulder Colorado USA To me, truth is not some vague, foggy notion. Truth is real. And, at the same time, unreal. Fiction and fact and everything in between, plus some things I can't remember, all rolled into one big 'thing'. This is truth, to me. -- Jack Handey