From owner-freebsd-stable@FreeBSD.ORG Wed Dec 7 21:34:59 2005 Return-Path: X-Original-To: freebsd-stable@freebsd.org Delivered-To: freebsd-stable@freebsd.org Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125]) by hub.freebsd.org (Postfix) with ESMTP id 4EBB516A41F; Wed, 7 Dec 2005 21:34:59 +0000 (GMT) (envelope-from vizion@vizion.occoxmail.com) Received: from dukecmmtao02.coxmail.com (dukecmmtao02.coxmail.com [68.99.120.69]) by mx1.FreeBSD.org (Postfix) with ESMTP id 0C50643D8B; Wed, 7 Dec 2005 21:34:55 +0000 (GMT) (envelope-from vizion@vizion.occoxmail.com) Received: from dns1 ([64.58.171.82]) by dukecmmtao02.coxmail.com (InterMail vM.6.01.05.02 201-2131-123-102-20050715) with ESMTP id <20051207213513.BBHF6953.dukecmmtao02.coxmail.com@dns1>; Wed, 7 Dec 2005 16:35:13 -0500 From: Vizion To: Doug Barton Date: Wed, 7 Dec 2005 13:34:53 -0800 User-Agent: KMail/1.8.3 References: <200512051518.43896.vizion@vizion.occoxmail.com> <200512061941.31866.vizion@vizion.occoxmail.com> <43974D99.7000809@FreeBSD.org> In-Reply-To: <43974D99.7000809@FreeBSD.org> MIME-Version: 1.0 Content-Type: text/plain; charset="iso-8859-1" Content-Transfer-Encoding: 7bit Content-Disposition: inline Message-Id: <200512071334.53884.vizion@vizion.occoxmail.com> Cc: freebsd-stable@freebsd.org Subject: Re: Upgrading 5.3 > 6.0 buildworld failure now in libmagic X-BeenThere: freebsd-stable@freebsd.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: Production branch of FreeBSD source code List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Wed, 07 Dec 2005 21:34:59 -0000 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.