From owner-freebsd-stable Thu Dec 23 18:29:45 1999 Delivered-To: freebsd-stable@freebsd.org Received: from mail.rdc3.on.home.com (ha1.rdc3.on.home.com [24.2.9.68]) by hub.freebsd.org (Postfix) with ESMTP id 7687514BFA for ; Thu, 23 Dec 1999 18:29:43 -0800 (PST) (envelope-from cwass99@home.com) Received: from tristan.net ([24.114.108.234]) by mail.rdc3.on.home.com (InterMail v4.01.01.02 201-229-111-106) with ESMTP id <19991224022731.OABU7552.mail.rdc3.on.home.com@tristan.net>; Thu, 23 Dec 1999 18:27:31 -0800 Content-Length: 2545 Message-ID: X-Mailer: XFMail 1.4.2 on FreeBSD X-Priority: 3 (Normal) Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: 8bit MIME-Version: 1.0 In-Reply-To: <19991223184115.4862.qmail@web504.mail.yahoo.com> Date: Thu, 23 Dec 1999 21:26:45 -0500 (EST) From: Colin To: Mike s Subject: Re: bugs in the handbook. (FreeBSD Portal) Cc: stable@FreeBSD.ORG Sender: owner-freebsd-stable@FreeBSD.ORG Precedence: bulk X-Loop: FreeBSD.ORG I don't think we don't care about the documentation, that strikes me as something of an oversimplification. There are 2 distinct problems here: 1) The peole who know enough about the system to document it properly generally don't have the time (or inclination...gotta love those programmers ;)) to spend on documentation. They're too busy fixing the problems that turn up regularly or adding enhancements (which is where most of the problems start ;)). 2) The peole who are most willing to spend time on the documentation don't have the specific knowledge to do it. They are the one's who would like to be reading the docs. Yes, I know it's inappropriate to generalize that much, but I think you get the idea. There is, of course, quite a lot of good documentation out there already, most of it accessible on-line. There is a definite need for ongoing improvement and upgrading, but I don't think that surprises anyone. There's an interesting article at http://www.firstmonday.org/issues/issue4_12/bezroukov/index.html that talks about the problems of documentation in the Open Software world. Actually, it is just a really good second look at the "Cathedral and Bazaar" with a section on documentation. The upshot is that we cannot accept the code as sufficient documentation for something this complex and there is a definite need for a complete higher level view. To meet that need there are several really good resources including "The Design and Implementation of the 4.4BSD Operating System", and "The Complete FreeBSD". There are,as well, several really good on-line reources, not least of which is the FreeBSD HowTo. I know there are more (not including the general Unix books) but titles escape me right now. Add the books to the FreeBSD specific web sites we already have, and i'm not sure the problem is lacking docs, rather slightly out of date docs due to an ambitious schedule of updates and releases. To start adding additional "Home of the Docs" sites would, IMHO, actually add to the confusion and difficulties. We would be much better served by people submitting pr's (where appropriate ;)) or suggestions that could be integrated into the existing docs. I'm not convinced (having wandered aimlessly down that road) the Linux style of documentation (1000's of sites, no real organization ;)) is the best bet here. On 23-Dec-1999 Mike s wrote: > Well, as i can see not many people care about the > documentation, or at least providing FreeBSD users > .......etc....................... To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-stable" in the body of the message