From owner-freebsd-questions Fri Mar 16 20:21:23 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 5FDE037B719 for ; Fri, 16 Mar 2001 20:21:20 -0800 (PST) (envelope-from mwm@mired.org) Received: (qmail 7421 invoked by uid 100); 17 Mar 2001 04:21:19 -0000 From: Mike Meyer MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: 7bit Message-ID: <15026.58943.554108.688513@guru.mired.org> Date: Fri, 16 Mar 2001 22:21:19 -0600 To: David Johnson Cc: questions@freebsd.org Subject: Re: documentation issues generally In-Reply-To: <22787522@toto.iv> 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 David Johnson types: > Ted Mittelstaedt wrote: > > I disagree with this. Rather, the problem is that programmers usually > > dislike > > "wasting time" on writing documentation. All of them that I've worked with > > are more than happy to have someone else do it. But, I've not sensed that > > anyone I've worked with has "looked down" on what I'm doing. > It's not that they consider it "wasting time", it's just that it's pure > drudgery. I've written documentation for my own programs, and am > currently helping with docs for KDE. It's not fun. It's boring. The > developers should be the ones writing the docs, since they know the > software the best, but they will probably be the ones least likely to > enjoy writing it. This is a base canard. 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. Before anyone gets offended, that's a *general* trend, and does not necessarily apply to any individual. But those who excel at both are rare and very valuable. 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. Having worked with a number of groups that provided rather technical products (enterprise level servers, for example) and their documentation, there are a number of common elements. One is that the documentation group was composed of different people than the implementation group. The other is that there were several levels of documentation, aimed at people with different levels of prior knowledge of the server. FreeBSD is pretty much a completely volunteer project. The only way to get better documentation is for someone to step up and *write* it - and then submit it back to the project. There's lots of things to work on; just choose one and have at it. 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