Upgrading 5.3 > 6.0 buildworld failure now in libmagic

[Peter Jeremy]

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