Date: Thu, 08 Dec 2005 10:27:44 -0700 From: secmgr <security@jim-liesl.org> To: Peter Jeremy <PeterJeremy@optushome.com.au> Cc: freebsd-stable@freebsd.org, Vizion <vizion@vizion.occoxmail.com> Subject: Re: Upgrading 5.3 > 6.0 buildworld failure now in libmagic Message-ID: <43986D10.9040503@jim-liesl.org> In-Reply-To: <20051208093442.GW32006@cirb503493.alcatel.com.au> 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>
next in thread | previous in thread | raw e-mail | index | archive | help
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
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?43986D10.9040503>