From owner-freebsd-questions Fri Mar 16 22:21:17 2001 Delivered-To: freebsd-questions@freebsd.org Received: from guru.mired.org (okc-65-26-235-186.mmcable.com [65.26.235.186]) by hub.freebsd.org (Postfix) with SMTP id C10A337B718 for ; Fri, 16 Mar 2001 22:21:14 -0800 (PST) (envelope-from mwm@mired.org) Received: (qmail 10322 invoked by uid 100); 17 Mar 2001 06:21:13 -0000 From: Mike Meyer MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: 7bit Message-ID: <15027.601.619946.802377@guru.mired.org> Date: Sat, 17 Mar 2001 00:21:13 -0600 To: "Doug Young" Cc: "Mike Meyer" , "David Johnson" , Subject: Re: documentation issues generally In-Reply-To: <002301c0aea8$77a7d380$0200a8c0@apana.org.au> References: <15026.58943.554108.688513@guru.mired.org> <002301c0aea8$77a7d380$0200a8c0@apana.org.au> X-Mailer: VM 6.89 under 21.1 (patch 14) "Cuyahoga Valley" XEmacs Lucid X-face: "5Mnwy%?j>IIV\)A=):rjWL~NB2aH[}Yq8Z=u~vJ`"(,&SiLvbbz2W`;h9L,Yg`+vb1>RG% *h+%X^n0EZd>TM8_IB;a8F?(Fb"lw'IgCoyM.[Lg#r\ Sender: owner-freebsd-questions@FreeBSD.ORG Precedence: bulk X-Loop: FreeBSD.ORG Doug Young 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. > 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 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