From owner-freebsd-doc Tue Apr 6 15:51:50 1999 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 DBAB115661 for ; Tue, 6 Apr 1999 15:51:31 -0700 (PDT) (envelope-from nik@nothing-going-on.demon.co.uk) Received: (from nik@localhost) by nothing-going-on.demon.co.uk (8.9.2/8.9.2) id TAA67699; Tue, 6 Apr 1999 19:11:59 +0100 (BST) (envelope-from nik) Date: Tue, 6 Apr 1999 19:11:59 +0100 From: Nik Clayton To: Sean Kelly Cc: Nik Clayton , doc@FreeBSD.ORG Subject: Re: Organisation change for the Handbook Message-ID: <19990406191159.D6083@catkin.nothing-going-on.org> References: <19990405234615.B6083@catkin.nothing-going-on.org> <370A3434.26DB3045@plutotech.com> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Mailer: Mutt 0.95.4i In-Reply-To: <370A3434.26DB3045@plutotech.com>; from Sean Kelly on Tue, Apr 06, 1999 at 10:20:04AM -0600 Organization: Nik at home, where there's nothing going on Sender: owner-freebsd-doc@FreeBSD.ORG Precedence: bulk X-Loop: FreeBSD.org On Tue, Apr 06, 1999 at 10:20:04AM -0600, Sean Kelly wrote: [ snippage; we're in agreement ] > > The gist of my proposal is to split the Handbook up in to a number of > > smaller books, containing between 70-150 'pages'. These would then truly be > > *hand*books. Each book should tackle one topic, and not repeat information > > from one of the other books. For example, if a book's topic requires that > > the reader reconfigure their kernel (for example, Firewalls), they should be > > directed to the appropriate part of the "Configuring FreeBSD" book, instead > > of repeating that information there. > > I mostly agree. In particular, kernel configuration is one of out > better chapters in the current handbook. Yet some amount of kernel > configuration appears in nearly all the other chapters: in networking on > setting up the kernel with an Ethernet controller; in printing on > setting up the kernel for parallel ports; etc. Yep. One of the things each book will need is a "_topic_ for the impatient". This is just bullet points that provide the minimal information for those that know what they're doing, and don't need handholding. For Kernel Configuration this would be something like; * Make sure you've installed the kernel sources. * Copy /sys/i386/conf/GENERIC /sys/i386/conf/KERNELNAME, where KERNELNAME is the name you want for your new kernel. * Read the comments in GENERIC and LINT (in the same directory) to determine which entries you need to add and remove. * # config -r KERNELNAME * # cd ../../compile/KERNELNAME # make clean depend # make all install * # shutdown -r now Obviously, the rest of the book goes in to much more detail. > I think the terminology is just tripping me up, here: are these really > separate books? Will these be toplevel Docbook "book" elements? I'm > wondering if there exists enough material in each book to warrant a > book, and thence a collection for all of our documentation. I think they are. I started off by thinking that this could be one big book, with each of these being 'parts' within that book (each part composed of many chapters). The more I thought about this, the more I thought that they may as well be books in their own right. It makes them a little more standalone, and means that the new user is not confronted with 580 pages of documentation to read in one lump. In DocBook terms, we'd have the FreeBSD documentation , consisting of many s. Of course, with clever SGML tricks the chapters (and books) can be agregated together in different ways, including producing one (big) book that includes the content of all the others, if there's a demand for that sort of thing. > > [ new organization ] > > Okay, I'm warming up to the idea now. In particular, "Unix Basics" > ought to be its own book. A Unix expert doesn't need all that extra > material if s/he just wants to know how to install FreeBSD. Yep. > Finally, don't forget that we'll need a separate book that's a compiled > index to the whole collection. Yep. A technical issue more than an organisational one. N -- Bagel: The carbohydrate with the hole To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-doc" in the body of the message