Date: Tue, 6 Apr 1999 19:11:59 +0100 From: Nik Clayton <nik@nothing-going-on.demon.co.uk> To: Sean Kelly <kelly@plutotech.com> Cc: Nik Clayton <nik@nothing-going-on.demon.co.uk>, doc@FreeBSD.ORG Subject: Re: Organisation change for the Handbook Message-ID: <19990406191159.D6083@catkin.nothing-going-on.org> In-Reply-To: <370A3434.26DB3045@plutotech.com>; from Sean Kelly on Tue, Apr 06, 1999 at 10:20:04AM -0600 References: <19990405234615.B6083@catkin.nothing-going-on.org> <370A3434.26DB3045@plutotech.com>
index | next in thread | previous in thread | raw e-mail
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 <set>, consisting of many <book>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
home |
help
Want to link to this message? Use this
URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?19990406191159.D6083>