Upgrading 5.3 > 6.0 buildworld failure now in libmagic

[Vizion]

On Wednesday 07 December 2005 13:01,  the author Doug Barton contributed to 
the dialogue on-
 Re: Upgrading 5.3 > 6.0 buildworld failure now in libmagic: 

>Vizion wrote:
>> Well I do not want to not thank those who have made the upgrades viable.
>> The value of their work should not be underrated.
>
>That's a step in the right direction, thanks. :)
>
>> There is however a perennial problem that freebsd documentation has always
>> been seen as behind and seperate from the development process rather than
>> an integral part of that process.
>
>You're right, however that is just "the way it is." 

Well having run many very large scale projects myself I  find it difficult to 
accept either implication of this perspective. The first implication is that 
we should be complacent about it and not seek to find a method to improve the 
process. The second implication is that top notch developers do not care 
about end user comfort. My experience is that most do care but they needa 
helpful environment to achieve food documentation.

>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.

What I have found works in development is to create team relationships that 
cover design, development and documentation. Unfortunately this does go 
against the somewhat individualistic elitist relationship that is 
unnecessarily sustained by the implications I referred to earlier (neither of 
which I buy and both of which seem to me to be condescending nonsense).

My view would be that the freebsd project might do well to consider 
implementing a "no release without quality documentation assurance" policy. 
Such a policy forces design and development to integrate their work with 
whoever has been identified as responsible for user documentation (whether 
that is the designer, developer or a seprate documentation person or team. 
This encourage the preparation of user documentation as part of the project 
rather then an afterthought (that depends upon members of the "hoi poloi".

>The documentation is light 
>years ahead of where it was 11 years ago when I started using FreeBSD for
>one simple reason. Interested users stepped up and helped make it better.
>That's the only way that things improve in an open source project.

OK so some of that talent needs to be harnessed and integrated into the 
development process. In this day and age we need to believe that user 
documentation provides a paradigm for design and development not design and 
development a paradigm for documentation. The latter view characterized 
development in the early 70,s and 80's. I thought we had moved beyond that.

>
>FWIW, I added a paragraph to the UPDATING file in both HEAD and RELENG_6
>that describes why updating to the latest code in the installed branch is a
>good idea before trying a major version upgrade. Hopefully that will help
>the next person who stumbles over this same issue.

Thank you so much for what you do. I trust that you will understand that 
recomendations for improvement are made BECAUSE the quality of design and 
development is so good. It deserves better and more professional attention to 
the role of end user documentation.

my two pennorth
>
>Doug

-- 
40 yrs navigating and computing in blue waters.
English Owner & Captain of British Registered 60' bluewater Ketch S/V Taurus.
 Currently in San Diego, CA. Sailing bound for Europe via Panama Canal after 
completing engineroom refit.