Date: Sat, 6 Apr 2002 15:11:26 -0800 From: Murray Stokely <murray@FreeBSD.org> To: Giorgos Keramidas <keramida@freebsd.org> Cc: Murray Stokely <murray@freebsd.org>, freebsd-doc@freebsd.org Subject: Re: Splitting the Handbook? (was: [a couple of new doc PRs]) Message-ID: <20020406231126.GP5732@freebsdmall.com> In-Reply-To: <20020406221709.GA1181@hades.hell.gr> References: <20020404062954.6607E2E827@mail.freebsdmall.com> <20020406221709.GA1181@hades.hell.gr>
next in thread | previous in thread | raw e-mail | index | archive | help
--x+6KMIRAuhnl3hBn
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
On Sun, Apr 07, 2002 at 01:17:09AM +0300, Giorgos Keramidas wrote:
> This is hard to search though. It's difficult for a newcomer to find his
> way around in this huge document. It is time, I think to separate the
> Handbook in smaller parts. The main thing that I was thinking about is how
It's been time for over 4 years, we've just never identified the
first concrete step to move in that direction.
> - Server machines.
> - Workstations.
> - (Both, but this can clearly be covered in the previous parts.)
I think that the 3rd printed edition (which I've obviously been
doing some initial planning for) should be split into two books along
these lines. I was planning on a "User's Guide" and an
"Administrator's Guide". If the FreeBSD Documentation Project makes
further subdivisions into smaller books, they can be mapped into these
two categories for print publication purposes. A collection of
smaller books is not practical for U.S. retail shelves, although if
done right it can make online browsing easier.
> But what can we hope to achieve by splitting the documentation in
> server/workstation categories? Well, for one thing, PRs like the two
The model you outlined works well for docs.sun.com, where tens of
thousands of pages of documentation are available. I'm definitely in
favor of higher level "collections" that can contain books / articles
on similar topics. For the 2nd Edition Handbook, we pulled in one of
the articles to supplement a chapter of the Handbook that was
lacking. We've gained many new articles since that time, so this sort
of overlap will become increasingly apparent.
> Internet mail works, to propose making this a separate book. One
> part, two parts (sysadmin & user), it's not really important to have
> everything organized and working perfectly right from the beginning.
> What is important is, what do you all thing about doing this? I could
I don't think splitting off one chapter of the Handbook is a good
place to start. I would rather start by splitting the Handbook in
two. If you just split this one chapter off, then you are stuck with
a weird inconsistency for as long as it takes us to finish the work
("Everything is in the handbook, ohh except for Internet Mail, that is
in a separate section"). If you start off by splitting the Handbook
in two based on the existing <part> divisions of the book ("Getting
Started", and "System Administration", with the appendices split
between the two as appropriate), then you don't sacrifice consistency
in any way.
> if I can hope in having your help & assistance in writing those
> sections I'm not very good with, or if you'd prefer all this to stay
> in the existing Handbook, as a chapter, perhaps two.
Above all else, I'd just like to see the content available, no
matter where it ends up. ;)
- Murray
--x+6KMIRAuhnl3hBn
Content-Type: application/pgp-signature
Content-Disposition: inline
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.0.6 (SunOS)
Comment: For info see http://www.gnupg.org
iD8DBQE8r4CdtNcQog5FH30RAsh3AJ9H7KjcgFTkWvwnAeV/uZn5f9W5MgCgxnqi
Y+hIwD66bKvbB9KIDQ0GMlE=
=giav
-----END PGP SIGNATURE-----
--x+6KMIRAuhnl3hBn--
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?20020406231126.GP5732>