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 ) id 1IxUa6-0005rb-Me for garchives@archives.gentoo.org; Wed, 28 Nov 2007 21:36:31 +0000 Received: from robin.gentoo.org (localhost [127.0.0.1]) by robin.gentoo.org (8.14.2/8.14.0) with SMTP id lASLZev5028622; Wed, 28 Nov 2007 21:35:40 GMT Received: from smtp.ferdyx.org (170.Red-213-96-222.staticIP.rima-tde.net [213.96.222.170]) by robin.gentoo.org (8.14.2/8.14.0) with ESMTP id lASLXUK7025883 for ; Wed, 28 Nov 2007 21:33:30 GMT Received: from localhost (localhost [127.0.0.1]) by smtp.ferdyx.org (Postfix) with ESMTP id 765A78D308 for ; Wed, 28 Nov 2007 22:33:57 +0100 (CET) X-Virus-Scanned: Debian amavisd-new at ferdyx.org Received: from smtp.ferdyx.org ([127.0.0.1]) by localhost (tungsteno.ferdyx.org [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id jcsyBYKJkrdL for ; Wed, 28 Nov 2007 22:33:54 +0100 (CET) Received: from localhost (unknown [213.121.151.206]) (using TLSv1 with cipher DHE-RSA-AES256-SHA (256/256 bits)) (No client certificate requested) by smtp.ferdyx.org (Postfix) with ESMTP id E54B28D307 for ; Wed, 28 Nov 2007 22:33:53 +0100 (CET) Date: Wed, 28 Nov 2007 21:33:19 +0000 From: Ciaran McCreesh To: gentoo-dev@lists.gentoo.org Subject: Re: [gentoo-dev] Re: [RFC] Features and documentation Message-ID: <20071128213319.09f73e89@blueyonder.co.uk> In-Reply-To: <20071128211405.GA11126@supernova> References: <20071127192144.GP4368@supernova> <474D53CA.7060101@gentoo.org> <20071128211405.GA11126@supernova> X-Mailer: Claws Mail 3.0.2 (GTK+ 2.12.1; x86_64-pc-linux-gnu) Precedence: bulk List-Post: List-Help: List-Unsubscribe: List-Subscribe: List-Id: Gentoo Linux mail X-BeenThere: gentoo-dev@gentoo.org Reply-to: gentoo-dev@lists.gentoo.org Mime-Version: 1.0 Content-Type: multipart/signed; boundary="Sig_/qKvPPzd6m4z.AUed=xLP4V+"; protocol="application/pgp-signature"; micalg=PGP-SHA1 X-Archives-Salt: cda2fff0-c4ab-40a5-9d02-62753949461a X-Archives-Hash: ebde1a2aebbcc05f1901c65a4c97b0f9 --Sig_/qKvPPzd6m4z.AUed=xLP4V+ Content-Type: text/plain; charset=US-ASCII Content-Transfer-Encoding: quoted-printable On Wed, 28 Nov 2007 13:14:05 -0800 Donnie Berkholz wrote: > Many of the replies keep asking for details -- details that don't > exist. Apply the concept abstractly: things that need to be > documented must have documentation available in the appropriate form > at the time they're committed. Which still doesn't bring anything discussable or implementable. A large part of why many things aren't documented is that people have very different ideas about what level of documentation is required; this does nothing to affect that. > 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. You know... Practical things, rather than things that make you feel good but go nowhere. --=20 Ciaran McCreesh --Sig_/qKvPPzd6m4z.AUed=xLP4V+ Content-Type: application/pgp-signature; name=signature.asc Content-Disposition: attachment; filename=signature.asc -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.4.7 (GNU/Linux) iD8DBQFHTd6f96zL6DUtXhERAom8AJ44JghN4DgOF+lPECkQJuKf3JDzEwCdGd3t AaR07w+s011k5CYSN//lF7g= =SNUX -----END PGP SIGNATURE----- --Sig_/qKvPPzd6m4z.AUed=xLP4V+-- -- gentoo-dev@gentoo.org mailing list