From owner-freebsd-hackers  Fri May  3 13:28:30 2002
Delivered-To: freebsd-hackers@freebsd.org
Received: from HAL9000.wox.org (12-232-222-90.client.attbi.com [12.232.222.90])
	by hub.freebsd.org (Postfix) with ESMTP
	id 7DF5D37B41E; Fri,  3 May 2002 13:28:24 -0700 (PDT)
Received: (from das@localhost)
	by HAL9000.wox.org (8.11.6/8.11.6) id g43KSKE25054;
	Fri, 3 May 2002 13:28:20 -0700 (PDT)
	(envelope-from das)
Date: Fri, 3 May 2002 13:28:20 -0700
From: David Schultz <dschultz@uclink.Berkeley.EDU>
To: "R. David Murray" <bitz@bitdance.com>
Cc: Terry Lambert <tlambert2@mindspring.com>,
	JJ Behrens <jj@nttmcl.com>, Dave Hayes <dave@jetcafe.org>,
	Brooks Davis <brooks@one-eyed-alien.net>,
	Michael Sierchio <kudzu@tenebras.com>,
	Drew Tomlinson <drew@mykitchentable.net>, bmah@FreeBSD.ORG,
	freebsd-hackers@FreeBSD.ORG, freebsd-stable@FreeBSD.ORG
Subject: Re: organic documentation
Message-ID: <20020503132820.A24949@HAL9000.wox.org>
Mail-Followup-To: "R. David Murray" <bitz@bitdance.com>,
	Terry Lambert <tlambert2@mindspring.com>, JJ Behrens <jj@nttmcl.com>,
	Dave Hayes <dave@jetcafe.org>,
	Brooks Davis <brooks@one-eyed-alien.net>,
	Michael Sierchio <kudzu@tenebras.com>,
	Drew Tomlinson <drew@mykitchentable.net>, bmah@FreeBSD.ORG,
	freebsd-hackers@FreeBSD.ORG, freebsd-stable@FreeBSD.ORG
References: <3CD2D513.C6566342@mindspring.com> <20020503142917.H32803-100000@twirl.bitdance.com>
Mime-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
In-Reply-To: <20020503142917.H32803-100000@twirl.bitdance.com>; from bitz@bitdance.com on Fri, May 03, 2002 at 02:34:40PM -0400
Sender: owner-freebsd-hackers@FreeBSD.ORG
Precedence: bulk
List-ID: <freebsd-hackers.FreeBSD.ORG>
List-Archive: <http://docs.freebsd.org/mail/> (Web Archive)
List-Help: <mailto:majordomo@FreeBSD.ORG?subject=help> (List Instructions)
List-Subscribe: <mailto:majordomo@FreeBSD.ORG?subject=subscribe%20freebsd-hackers>
List-Unsubscribe: <mailto:majordomo@FreeBSD.ORG?subject=unsubscribe%20freebsd-hackers>
X-Loop: FreeBSD.ORG

Thus spake R. David Murray <bitz@bitdance.com>:
> On Fri, 3 May 2002, Terry Lambert wrote:
> > Aside from the classification problem (everyone has to classify
> > the same way for them to be able to get the information out),
> > the human factors argue that the depth should not exceed 3 on
> > any set of choices, before you get to what you want (HCI studies
> > at Bell Labs confirms this number).
> 
> Sorry for dropping in to the middle of a conversation, but this
> comment puzzles me.  I fail to see how:
> 
>   handbook + per-page comments from readers
> 
> is *inferior* to:
> 
>    handbook with no comments

I remember those comments in the PHP manual from back when I used PHP.
More often than not, they were wrong or misleading.  Yes, this is
worse than no comments at all.  Anyone can submit changes to the
FreeBSD documentation as it is; they're just forced to carefully think
out the changes they want to make, rather than submitting one-line
apothegms from a web browser.

To Unsubscribe: send mail to majordomo@FreeBSD.org
with "unsubscribe freebsd-hackers" in the body of the message