Date: Fri, 9 Dec 2005 11:37:42 -0800 From: "vizion" <vizion@vizion.occoxmail.com> To: "'Michael C. Shultz'" <ringworm01@gmail.com>, <freebsd-stable@freebsd.org> Cc: 'Peter Jeremy' <PeterJeremy@optushome.com.au>, 'Doug Barton' <dougb@freebsd.org> Subject: Freebsd Stable documentation Message-ID: <000101c5fcf8$05dbd870$59ab3a40@sleuth> In-Reply-To: <200512081102.58615.ringworm01@gmail.com>
next in thread | previous in thread | raw e-mail | index | archive | help
Thiis was originally=20 Upgrading 5.3 > 6.0 buildworld failure now in libmagic And on Mike Shultz recommendation I have relabeled the topic =20 > On Thursday 08 December 2005 08:57, vizion@vizion.occoxmail.com wrote: > > > From: Peter Jeremy <PeterJeremy@optushome.com.au> > > > Date: 2005/12/08 Thu AM 01:34:42 PST > > > 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 > > > > > > 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. > > >=20 <stuff cutout>>=20
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?000101c5fcf8$05dbd870$59ab3a40>