Skip site navigation (1)Skip section navigation (2)
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>

next in thread | previous in thread | raw e-mail | index | archive | help
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




Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?19990406191159.D6083>