From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from lists.gentoo.org ([140.105.134.102] helo=robin.gentoo.org) by finch.gentoo.org with esmtp (Exim 4.60) (envelope-from <gentoo-dev+bounces-27790-garchives=archives.gentoo.org@gentoo.org>) id 1IxXKC-0006FQ-2L for garchives@archives.gentoo.org; Thu, 29 Nov 2007 00:32:16 +0000 Received: from robin.gentoo.org (localhost [127.0.0.1]) by robin.gentoo.org (8.14.2/8.14.0) with SMTP id lAT0VRm5030175; Thu, 29 Nov 2007 00:31:27 GMT Received: from smtp.gentoo.org (smtp.gentoo.org [140.211.166.183]) by robin.gentoo.org (8.14.2/8.14.0) with ESMTP id lAT0TWSK027858 for <gentoo-dev@lists.gentoo.org>; Thu, 29 Nov 2007 00:29:32 GMT Received: from gentoo.org (c-67-171-150-177.hsd1.or.comcast.net [67.171.150.177]) (using TLSv1 with cipher DHE-RSA-AES256-SHA (256/256 bits)) (No client certificate requested) by smtp.gentoo.org (Postfix) with ESMTP id 0F09B6558D for <gentoo-dev@lists.gentoo.org>; Thu, 29 Nov 2007 00:29:32 +0000 (UTC) Date: Wed, 28 Nov 2007 16:29:30 -0800 From: Donnie Berkholz <dberkholz@gentoo.org> To: gentoo-dev@lists.gentoo.org Subject: Re: [gentoo-dev] Re: [RFC] Features and documentation Message-ID: <20071129002929.GA11249@supernova> References: <20071127192144.GP4368@supernova> <474D53CA.7060101@gentoo.org> <pan.2007.11.28.12.38.43@cox.net> <20071128211405.GA11126@supernova> <20071128213319.09f73e89@blueyonder.co.uk> Precedence: bulk List-Post: <mailto:gentoo-dev@lists.gentoo.org> List-Help: <mailto:gentoo-dev+help@gentoo.org> List-Unsubscribe: <mailto:gentoo-dev+unsubscribe@gentoo.org> List-Subscribe: <mailto:gentoo-dev+subscribe@gentoo.org> List-Id: Gentoo Linux mail <gentoo-dev.gentoo.org> X-BeenThere: gentoo-dev@gentoo.org Reply-to: gentoo-dev@lists.gentoo.org MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <20071128213319.09f73e89@blueyonder.co.uk> User-Agent: Mutt/1.5.16 (2007-06-09) X-Archives-Salt: 89db244a-6945-4b19-951d-d8f41e015abc X-Archives-Hash: b452c87f854b37b3b891bb584f5e2e39 On 21:33 Wed 28 Nov , Ciaran McCreesh wrote: > On Wed, 28 Nov 2007 13:14:05 -0800 > > What remains unclear about this principle? > > It's entirely nebulous and has nothing that can be discussed or agreed > upon, beyond giving people a feel good "ooh, yes, we should do this" > with no practical purpose. It has an unpleasant smell of something a > Dilbert-esque manager would introduce after having read a "Project > Management for Dummies" book full of slogans and generalities. > > So, if you want to take this somewhere useful: > > * Decide what the scope of a change is. Are we talking anything > user-visible? Anything substantially user-visible? Anything requiring > user action? Anything developer-visible? Anything requiring developer > action? Anything visible to small numbers of developers working in a > specific area? > > * Decide what the appropriate level of documentation is. > > * Discuss how you're going to get documentation of a sufficiently high > quality. Most developers aren't going to go out and spend several months > studying technical writing... > > * Decide whether it's worth putting the limited available writing > resources into developer documentation that will only be read by a few > hundred people, rather than putting more focus into user documentation > that will be read by pretty much everyone. I think that in most cases it is self-evident to the developer how much documentation is useful, and if the community disagrees with that developer, anyone else is welcome to say so. There are always a few people out on the edge, but most people realize how much documentation should exist. I don't see a benefit to all these precise specifications. Thanks, Donnie -- gentoo-dev@gentoo.org mailing list