Date: Sat, 17 Mar 2001 16:06:36 +1000 From: "Doug Young" <dougy@bryden.apana.org.au> To: "Mike Meyer" <mwm@mired.org>, "David Johnson" <djohnson@acuson.com> Cc: <questions@FreeBSD.ORG> Subject: Re: documentation issues generally Message-ID: <002301c0aea8$77a7d380$0200a8c0@apana.org.au> References: <15026.58943.554108.688513@guru.mired.org>
next in thread | previous in thread | raw e-mail | index | archive | help
The following comments should be made into a huge "flashing lights" sign & put in front of the docs people !! > 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. 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?002301c0aea8$77a7d380$0200a8c0>