From owner-freebsd-questions Mon Mar 19 12:26:43 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 B56BA37B71C for ; Mon, 19 Mar 2001 12:26:37 -0800 (PST) (envelope-from mwm@mired.org) Received: (qmail 12964 invoked by uid 100); 19 Mar 2001 20:26:36 -0000 From: Mike Meyer MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: 7bit Message-ID: <15030.27516.375707.37930@guru.mired.org> Date: Mon, 19 Mar 2001 14:26:36 -0600 To: David Johnson Cc: questions@freebsd.org Subject: Re: documentation issues generally In-Reply-To: <3AB650A1.F85EB64D@acuson.com> References: <15026.58943.554108.688513@guru.mired.org> <3AB650A1.F85EB64D@acuson.com> 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: > Mike Meyer wrote: > > 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. > Let me rephrase slightly. The developer should be the one *responsible* > for the documentation. He might not be the one actually writing it, but > if he isn't he should be tapping someone to do the work. Not a bad idea - except it clashes with *every* project I've ever worked on that actually had a documentation team, even if the team was only one person. The project manager is responsible for the documentation. The documentation group is responsible for writing it, and usually responsible for gathering the information, as well. Whether it comes from the engineers varied from group to group. Of course, I don't think FreeBSD *has* a project manager. > Otherwise you end up with software with no documentation, an all too > frequent occurance. I would claim that's a sign you've done things backwards. The best documentation from any group I've worked with came from DEC, which was also the only group to do user-centriec docs. The software engineers didn't get involved until after the docs were written - their job was to *implement* the documentation. > No, Einstein shouldn't be teaching the freshmen, but he should be > teaching someone or his knowledge is going to waste. Publishing - as opposed to teaching - is probably the most effective use of his time when it comes to transfering knowledge. 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