Stable Doc issues- thread branched from [Upgrading 5.3 > 6.0 buildworld failure]

[Vizion]

On Wednesday 07 December 2005 13:34,  the author Vizion contributed to the 
dialogue on-
 Re: Upgrading 5.3 > 6.0 buildworld failure now in libmagic now 
Stable Doc issues- thread branched from [Upgrading 5.3 > 6.0 buildworld 
failure]
>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
>
Just another thought - it seems that the current philosophy is
We know generally what you the users want and you will know exactly what you 
have got when we have done it!!
When we have done we will give it to you for you to sort out how you can use 
it!
Ps. If you fo not like what we have done or the way we have done it you need 
to be reminded you are lucky we have done it for you!!

Come on - it just cannot be like this for ever. 

Open source projects start like this but as they mature does not the 
concentatration need to shift towards user satisfaction rather than just a 
constant gallop towards greater technical functionality.

david

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