From owner-freebsd-doc Tue Apr 4 13:38:29 2000 Delivered-To: freebsd-doc@freebsd.org Received: from nothing-going-on.demon.co.uk (nothing-going-on.demon.co.uk [193.237.89.66]) by hub.freebsd.org (Postfix) with ESMTP id F315F37B98D; Tue, 4 Apr 2000 13:38:06 -0700 (PDT) (envelope-from nik@nothing-going-on.demon.co.uk) Received: (from nik@localhost) by nothing-going-on.demon.co.uk (8.9.3/8.9.3) id SAA71141; Tue, 4 Apr 2000 18:19:24 +0100 (BST) (envelope-from nik) Date: Tue, 4 Apr 2000 18:19:23 +0100 From: Nik Clayton To: Michael Chin-yuan Wu Cc: dillon@backplane.com, nik@freebsd.org, briggs@ninthwonder.com, jim@freebsd.org, freebsd-doc@freebsd.org Subject: Re: Handbook: FreeBSD Internals- Request for Review Message-ID: <20000404181923.A64168@catkin.nothing-going-on.org> References: Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Mailer: Mutt 1.0.1i In-Reply-To: ; from mwu@ece.utexas.edu on Sun, Apr 02, 2000 at 11:26:28AM -0500 Organization: FreeBSD Project Sender: owner-freebsd-doc@FreeBSD.ORG Precedence: bulk X-Loop: FreeBSD.org On Sun, Apr 02, 2000 at 11:26:28AM -0500, Michael Chin-yuan Wu wrote: > I have finally finished editing and rewriting the > FreeBSD Handbook's section on the FreeBSD VM System > > The most up-to-date version will be on > http://www.ece.utexas.edu/~mwu/_working_copy_new_chapter24.txt Looks good. I assume you've been doing this in DocBook, and that's just the result of converting it to text. > This document is very long. What should we do about it? > A. Split it into several chapter. > B. Leave it as is. C. Create the "FreeBSD Hackers Handbook" I favour option C. :-), possibly calling it the "FreeBSD Developer's Handbook" instead. The s in your doc then become s in their own right. Trying to stuff everything in to the Handbook is, IMHO, a bad idea. The existing Handbook can be the "Users' Handbook", this new document can be for developers. The two audiences are separate. Other topics for a developer's handbook would be "Writing KLDs", "Writing device drivers", "Writing syscons screensavers", ... Probably a structure akin to: Introduction Architectural Overview The Kernel The VM System IPv4 IPv6/IPsec [...] Kernel Loadable [ er, what does the 'd' in 'kld' stand for? ] Syscons We might be able to pull in chapters 21 ("Adding new Kernel Configuration Options") and 22 ("Kernel Debugging") as well. 21 isn't really needed in a user-level document, although I can see a case for keeping 22 in the main Handbook. FWIW, IMHO Chapter 4.4 ("Making a port yourself") can be ripped out of the Handbook and in to its own "Porters Handbook"). It's a huge amount of text, most of which isn't useful to a 'normal' FreeBSD user. The "Contributing to FreeBSD" chapter can then point people at these documents ("Hackers Handbook", "Porters Handbook", "FDP Primer") depending on what potential contributors want to do. Thoughts? N -- Internet connection, $19.95 a month. Computer, $799.95. Modem, $149.95. Telephone line, $24.95 a month. Software, free. USENET transmission, hundreds if not thousands of dollars. Thinking before posting, priceless. Somethings in life you can't buy. For everything else, there's MasterCard. -- Graham Reed, in the Scary Devil Monastery To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-doc" in the body of the message