Date: Thu, 8 Dec 2005 20:34:42 +1100 From: Peter Jeremy <PeterJeremy@optushome.com.au> To: Vizion <vizion@vizion.occoxmail.com> Cc: Doug Barton <dougb@freebsd.org>, freebsd-stable@freebsd.org Subject: Re: Upgrading 5.3 > 6.0 buildworld failure now in libmagic Message-ID: <20051208093442.GW32006@cirb503493.alcatel.com.au> In-Reply-To: <200512071334.53884.vizion@vizion.occoxmail.com> References: <200512051518.43896.vizion@vizion.occoxmail.com> <200512061941.31866.vizion@vizion.occoxmail.com> <43974D99.7000809@FreeBSD.org> <200512071334.53884.vizion@vizion.occoxmail.com>
next in thread | previous in thread | raw e-mail | index | archive | help
On Wed, 2005-Dec-07 13:34:53 -0800, Vizion wrote: >Well having run many very large scale projects myself I find it difficult to >accept either implication of this perspective. There's a massive difference between running a large commercial project and running a large open source project using volunteers. On a commercial project, you can direct someone to do something and they have a choice of either doing it or finding another job. On a volunteer project, there's a limit to how far you can push someone to do something they don't enjoy before they just leave. > The first implication is that >we should be complacent about it and not seek to find a method to improve the >process. I don't think anyone is suggesting this. In my experience, the FreeBSD project is always open to process improvements - this is especially obvious in the documentation and release engineering areas. >>Most of our really top >>notch developers are actually very bad at documenting their work (I don't >>mean bad at being timely with it, I mean that they are bad at DOING it), and >>frankly their time is better spent elsewhere. > >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). 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. >What I have found works in development is to create team relationships that >cover design, development and documentation. I agree that this is a good approach. It's similar to the 'surgical team' approach that Brooks recommends in "The Mythical Man-Month". I think that this does happen to some extent in FreeBSD but agree it could be more widespread. (Though it is probably harder to put it into practice in a distributed, volunteer project than when the team share a cubicle). >My view would be that the freebsd project might do well to consider >implementing a "no release without quality documentation assurance" policy. ... >development is so good. It deserves better and more professional attention to >the role of end user documentation. Are you volunteering? -- Peter Jeremy
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20051208093442.GW32006>