Date: Sat, 17 Mar 2001 00:21:13 -0600 From: Mike Meyer <mwm@mired.org> To: "Doug Young" <dougy@bryden.apana.org.au> Cc: "Mike Meyer" <mwm@mired.org>, "David Johnson" <djohnson@acuson.com>, <questions@FreeBSD.ORG> Subject: Re: documentation issues generally Message-ID: <15027.601.619946.802377@guru.mired.org> In-Reply-To: <002301c0aea8$77a7d380$0200a8c0@apana.org.au> References: <15026.58943.554108.688513@guru.mired.org> <002301c0aea8$77a7d380$0200a8c0@apana.org.au>
next in thread | previous in thread | raw e-mail | index | archive | help
Doug Young <dougy@bryden.apana.org.au> types: > The following comments should be made into a huge "flashing lights" > sign & > put in front of the docs people !! Oh, I think they know all of it, but sometimes forget it. I think the back half - which you elided - needs to be hung in front of everyone who's not happy with the documentation in huge flashing lights. <mike > > Just because someone is most familiar with a > > bag of bits does *not* mean they are the ones who should be > explaining > > it to others, or the ones who are best able to do so. Otherwise, > you'd > > argue that Einstein should have taught froshling physics. > > > > The first problem in this case is that the ability to write C well > (or > > Python, or Perl, or anything else except maybe COBOL) does not infer > > the ability to write English well. In general, the opposite seems to > > be true - the better code someone writes, the worse documentation > > they'll write. > > > > The other problem is there is a natural tendency to explain what the > > author needs to know to use a program. This is a short list for > > someone who's been working with BSD daily for 20 years. It's a much > > longer list for someone who's on their second install. It's a very > > long list indeed for someone who has as yet to find the power switch > > on any computer. It's an intractably long list for someone the > author > > doesn't share a natural language with. One of the things that make > > good documentation people rare is that the ability to find an > > appropriate level of previous understanding to assume is uncommon. > > > -- Mike Meyer <mwm@mired.org> http://www.mired.org/home/mwm/ Independent WWW/Perforce/FreeBSD/Unix consultant, email for more information. To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-questions" in the body of the message
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?15027.601.619946.802377>