Date: Tue, 4 Apr 2000 23:35:11 -0700 From: Jim Mock <jim@FreeBSD.org> To: Nik Clayton <nik@FreeBSD.ORG> Cc: Michael Chin-yuan Wu <mwu@ece.utexas.edu>, freebsd-doc@FreeBSD.ORG Subject: Re: Handbook: FreeBSD Internals- Request for Review Message-ID: <20000404233511.B486@luna.cdrom.com> In-Reply-To: <20000404181923.A64168@catkin.nothing-going-on.org>; from nik@FreeBSD.ORG on Tue, Apr 04, 2000 at 06:19:23PM %2B0100 References: <Pine.SOL.3.93.1000402112529.9056A-100000@tick.ece.utexas.edu> <20000404181923.A64168@catkin.nothing-going-on.org>
next in thread | previous in thread | raw e-mail | index | archive | help
[Cc: list trimmed down to just Michael and -doc] On Tue, 04 Apr 2000 at 18:19:23 +0100, Nik Clayton wrote: > 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. Actually, as he said in his reply, he's doing it in plain text. I find it's easier for me to mark up the plain text than go through it as DocBook already and try to fix errors. > > 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 <sect1>s in your doc then become <chapter>s in > their own right. I *really* like this idea. I think we should definitely do this, and do it as soon as we can. > 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. Thank you, thank you, thank you :-) I've been noticing this as I've been going through what we have, and I have to agree wholeheartedly.. a lot of the stuff isn't relevant (IMO, at least) to the 'average joe' type user which the handbook is meant to cater to. > 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. Again this all sounds great. Here's some info on what I plan to do to get this thing to the printers. Since the handbook is an ever-changing document, I basically plan to take a 'snapshot' it as is (or as is in a day or two) and put it up elsewhere for the reviewers. This'll make it much easier as far as fixing errors and reviewing go.. I won't be trying to hit a moving target. Since everyone who's replied to you seems to be in agreement that this is a good thing, when I do the above, I'll cut out the more 'advanced' bits. It'll also give us additional books to publish down the road sometime if we want to :-) > 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. Sounds good. > 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. This sounds good too. > Thoughts? I say we do it. Let me know what I can do to help you get this done. - jim -- - jim mock - walnut creek cdrom/freebsd test labs - jim@luna.cdrom.com - - phone: 1.925.691.2800 x.3814 - fax: 1.925.674.0821 - jim@FreeBSD.org - - editor - The FreeBSDzine - www.freebsdzine.org - jim@freebsdzine.org - To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-doc" in the body of the message
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20000404233511.B486>