> > From: Peter Jeremy <[EMAIL PROTECTED]> > Date: 2005/12/08 Thu AM 01:34:42 PST > To: Vizion <[EMAIL PROTECTED]> > CC: Doug Barton <[EMAIL PROTECTED]>, freebsd-stable@freebsd.org > Subject: Re: Upgrading 5.3 > 6.0 buildworld failure now in libmagic > > 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. Not really I have done both and found that shared values and community collaboration work the same.
>On a commercial > project, you can direct someone to do something and they have a choice of > either doing it or finding another job. Well that kind of development environment (rule by dictat) does not work very well. Developers are people who are engaged in a collaborative process. If you encourage them to think like prima donas then they will behave like prima donas rather than as part of an integrated team. >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. Push has it limitations everywhere.. goals and communal rewards are better in both volunteer and commercial projects. > > > 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. > The question is about the degree of committment to process change not whwther it is absent or present. The critique is there is tooo little comitment to process change and too much resistance to greater concentration on the quality of user docuimentation and the significance of that work in the developmenmt cycle. > >>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. NOTE I said" F:ranky my experience has been that developers who are bad at ENSURING their work is well documentated are second rate rather than top rate developers. The work of the technical writer needs to influence development at the design stage! It does not matter whether the developer does or does not write the the documentation but it does matter whether the developer is COMIITED to both ensuring that there is proper documentation AND that the documentation process is an integral part of the development process that influences its outcome. >They may write a rough outline but > it's the technical writers who actually do the documentation. The outline for user documentation needs to be structured BEFORE development begins NOT as an afterthought. In a well structured development environment documentation is part of DESIGN not post design implementation . That is because thinking about end user at the design stage is necessary if the outcome of the process is going to be user centric. >The > problem is finding people with technical writing skills who are > interested in helping with FreeBSD. > Freebsd needs to reorganize the way it develops if it is going to interest techn ical writers. No technical writer wants to be associated with writing documnets for developments that have been poorly designed for the end user. Clearing up someone else's mess is no fun. If you treat technical writers as people who come along afterwards and pick up yopur trash OF COURSE you will not get them involved. You need to ask WHY it is difficult to get them. It is because freebsd does not produce software with a focus on end user satisfaction. This is a chicken and egg problem that can only be solved by a fu8ndamental shift both the focus of development objectives and the development process. > > 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). > I do not agree -- it mkay be harder for some people to accept that they cannot be part of a freebsd development team if they are not committed to playing their part in ensuring high quality documentaion and the need for integrating documentation into the development process. there can be no place for prima donas in a communal development project. > >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? I would if I saw signs of change but I am pretty despairfull about how illing the core group are to revising the way in which the process happens. The way things have been throughout freebsd history does not give me much confidence of its capacity to make the philosophical and structural changes that are needed to make user documentation a key part of the devlopmental cycle with an ability for user friendliness and user needs to influence the what, why, how, when and (and even the where) of devlopment. I think there may be greater hope in creating a project that can place an interface layer that runs on top of freebsd to ensure that freebsd is relevant in ten years. That is a project I am currently thinking about and wondering whether I have the time and energy available to kick start such an endeavor. > _______________________________________________ freebsd-stable@freebsd.org mailing list http://lists.freebsd.org/mailman/listinfo/freebsd-stable To unsubscribe, send any mail to "[EMAIL PROTECTED]"
