From owner-freebsd-doc  Mon Jun 26  2: 6: 8 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 17DCD37BDE5; Mon, 26 Jun 2000 02:05:56 -0700 (PDT)
	(envelope-from nik@nothing-going-on.demon.co.uk)
Received: from kilt.nothing-going-on.org (kilt.nothing-going-on.org [192.168.1.18])
	by nothing-going-on.demon.co.uk (8.9.3/8.9.3) with ESMTP id IAA88193;
	Mon, 26 Jun 2000 08:25:29 +0100 (BST)
	(envelope-from nik@catkin.nothing-going-on.org)
Received: (from nik@localhost)
	by nothing-going-on.demon.co.uk (8.9.3/8.9.3) id TAA00536;
	Sun, 25 Jun 2000 19:55:06 GMT
	(envelope-from nik)
Date: Sun, 25 Jun 2000 19:55:06 +0000
From: Nik Clayton <nik@freebsd.org>
To: doc@freebsd.org
Cc: dgl@bsdi.com, jim@cdrom.com, papowell@astart.com,
	wpaul@freebsd.org, ceren@magnesium.net, ryan@ryan.net,
	murray@bsdi.com
Subject: Splitting the Handbook
Message-ID: <20000625195506.E470@kilt.nothing-going-on.org>
Mime-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
User-Agent: Mutt/1.2i
Organization: FreeBSD Project <URL:http://www.freebsd.org/>
Sender: owner-freebsd-doc@FreeBSD.ORG
Precedence: bulk
X-Loop: FreeBSD.org

This has been on the cards for ages.

IMHO, the Handbook, as it stands, is unwieldy.  It's too big, it tries to
cater to too many audiences (someone installing FreeBSD, someone using
FreeBSD, someone trying to develop with FreeBSD, someone who wants to hack
on FreeBSD), and there's no one person that 'owns' it.

I want to break the Handbook up in to smaller chunks.  We're doing this
already -- the recent creation of the Porter's Handbook reflects this, as
does the work that Jeroen's doing on the Developer's Handbook.

[ In fact, if rumour is to be believed, Jim Mock spent most of last night
  locked in his hotel room putting together a "New Users Handbook" -- given
  the amount of alcohol on offer that's dedication. ]

Ideally, we would have a collection of *true* handbooks.  70-100 pages in
length and dealing with one topic at a time.

My last proposal for this is still available, at

    http://people.freebsd.org/~nik/hb/comments.txt

and

    http://people.freebsd.org/~nik/hb/new-layout.txt

I also think this would make the job of merging in documentation from other
projects (and, in particular, forming a "BSD Documentation Project")
considerably easier.

With the Handbook as it currently stands, trying to do this would mean that
large sections would be marked as OS specific.  For example, the
'installing' section.

Under this scheme, we would have an "Installation Handbook".  This can be
different on a per-project basis, and deserves to be.  But we would also
have a "Printing Handbook" which would have very little OS specific detail.

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