From owner-freebsd-stable@FreeBSD.ORG Thu Dec 8 17:30:46 2005 Return-Path: X-Original-To: freebsd-stable@freebsd.org Delivered-To: freebsd-stable@freebsd.org Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125]) by hub.freebsd.org (Postfix) with ESMTP id 84A7A16A420 for ; Thu, 8 Dec 2005 17:30:46 +0000 (GMT) (envelope-from security@jim-liesl.org) Received: from mta13.adelphia.net (mta13.adelphia.net [68.168.78.44]) by mx1.FreeBSD.org (Postfix) with ESMTP id 7DA8943D7F for ; Thu, 8 Dec 2005 17:30:30 +0000 (GMT) (envelope-from security@jim-liesl.org) Received: from daemon.jim-liesl.org ([70.33.46.68]) by mta13.adelphia.net (InterMail vM.6.01.05.02 201-2131-123-102-20050715) with ESMTP id <20051208173029.TMXA28251.mta13.adelphia.net@daemon.jim-liesl.org>; Thu, 8 Dec 2005 12:30:29 -0500 Received: from daemon.jim-liesl.org (localhost.clspco.adelphia.net [127.0.0.1]) by daemon.jim-liesl.org (Postfix) with ESMTP id 4DFD6610C; Thu, 8 Dec 2005 10:33:35 -0700 (MST) Received: from [127.0.0.1] (daemon.clspco.adelphia.net [192.168.1.15]) by daemon.jim-liesl.org (Postfix) with ESMTP id D3B39610A; Thu, 8 Dec 2005 10:33:34 -0700 (MST) Message-ID: <43986D10.9040503@jim-liesl.org> Date: Thu, 08 Dec 2005 10:27:44 -0700 From: secmgr User-Agent: Mozilla Thunderbird 0.8 (Windows/20040913) X-Accept-Language: en-us, en MIME-Version: 1.0 To: Peter Jeremy References: <200512051518.43896.vizion@vizion.occoxmail.com> <200512061941.31866.vizion@vizion.occoxmail.com> <43974D99.7000809@FreeBSD.org> <200512071334.53884.vizion@vizion.occoxmail.com> <20051208093442.GW32006@cirb503493.alcatel.com.au> In-Reply-To: <20051208093442.GW32006@cirb503493.alcatel.com.au> Content-Type: text/plain; charset=ISO-8859-1; format=flowed Content-Transfer-Encoding: 7bit X-Virus-Scanned: ClamAV using ClamSMTP Cc: freebsd-stable@freebsd.org, Vizion Subject: Re: Upgrading 5.3 > 6.0 buildworld failure now in libmagic X-BeenThere: freebsd-stable@freebsd.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: Production branch of FreeBSD source code List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Thu, 08 Dec 2005 17:30:46 -0000 Peter Jeremy wrote: >On Wed, 2005-Dec-07 13:34:53 -0800, Vizion wrote: > > >>That is a judgment call - franky my experience has been that developers who >>are bad at ensuring their work is well documentated are second rate rather >>than top rate developers. >> >> > >Software developers are notoriously poor at writing documentation for >non-technical people. There are probably very few developers who >enjoy writing end-user documentation (and can write). > My personal expectation is *not* that the FreeBSD developers tell me what a cdrom is. My expectation is that they tell me what works, what doesn't, and warn me about whats in the middle. Trust me, there are damn few "non-technical" people installing FreeBSD, and I'm pretty sure both of them gave up in sysinstall. I can read (most) code and I can search PR's. However, if it's 2 am and my server has puked on it's shoes during an upgrade due to an undocumented issue the developer knew about, I'm not going to recommend FreeBSD to anyone other than as a hobby for single men with beards. >In my >experience, especially on large projects, it's rare for developers to >write the end-user documentation. They may write a rough outline but >it's the technical writers who actually do the documentation. The >problem is finding people with technical writing skills who are >interested in helping with FreeBSD. > >It's also worth noting that a number of FreeBSD developers are not native >English speakers. It's probably unreasonable to expect them to write >polished English documentation. > > Again, I'm not asking them to write chapters in the handbook and I understand (and assumed) they may not be native English speakers. How hard is it to get a, "ata.c broke with via 666 sata chipset under heavy load"? If I have a via 666 sata chipset, now I know to go looking in the code. Even if don't go looking in the code, I know that I might want to look at a different adapter. Don't tell me whats little more than a subject line of a mail message is beyond even a junior non-English speaking coder and a few minutes with a translation program. > Are you volunteering? Yes, I'd like to help, not that I think my writing skills are all that great. But "no" if the developers won't be forthcoming with details. P.S. I'm not picking on the ata code or it's owners. It was just a module name I knew off hand. jim