From owner-freebsd-questions Fri Mar 16 22: 6:25 2001 Delivered-To: freebsd-questions@freebsd.org Received: from bryden.apana.org.au (bryden.apana.org.au [203.3.126.129]) by hub.freebsd.org (Postfix) with ESMTP id C19E237B719 for ; Fri, 16 Mar 2001 22:06:20 -0800 (PST) (envelope-from dougy@bryden.apana.org.au) Received: from roadrunner ([192.168.0.2]) by bryden.apana.org.au (8.9.3/8.9.3) with SMTP id QAA00843; Sat, 17 Mar 2001 16:05:58 +1000 (EST) (envelope-from dougy@bryden.apana.org.au) Message-ID: <002301c0aea8$77a7d380$0200a8c0@apana.org.au> From: "Doug Young" To: "Mike Meyer" , "David Johnson" Cc: References: <15026.58943.554108.688513@guru.mired.org> Subject: Re: documentation issues generally Date: Sat, 17 Mar 2001 16:06:36 +1000 MIME-Version: 1.0 Content-Type: text/plain; charset="iso-8859-1" Content-Transfer-Encoding: 7bit X-Priority: 3 X-MSMail-Priority: Normal X-Mailer: Microsoft Outlook Express 5.50.4133.2400 X-MimeOLE: Produced By Microsoft MimeOLE V5.50.4133.2400 Sender: owner-freebsd-questions@FreeBSD.ORG Precedence: bulk X-Loop: FreeBSD.ORG 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