Freebsd Stable documentation

[vizion]

Thiis was originally 
Upgrading 5.3 > 6.0 buildworld failure now in libmagic
And on Mike Shultz recommendation I have relabeled the topic

 
> On Thursday 08 December 2005 08:57, vizion at vizion.occoxmail.com wrote:
> > > From: Peter Jeremy <PeterJeremy at optushome.com.au>
> > > Date: 2005/12/08 Thu AM 01:34:42 PST
> > > To: Vizion <vizion at vizion.occoxmail.com>
> > > CC: Doug Barton <dougb at freebsd.org>,  freebsd-stable at 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.
> >
> 
<stuff cutout>>