Date: Mon, 12 Apr 1999 16:41:01 -0700 From: "Jordan K. Hubbard" <jkh@zippy.cdrom.com> To: Nik Clayton <nik@nothing-going-on.demon.co.uk> Cc: Greg Lehey <grog@lemis.com>, FreeBSD Documenters <doc@FreeBSD.ORG>, "Robert A. Bruce" <rab@cdrom.com> Subject: Re: Publishing the FreeBSD handbook Message-ID: <57153.923960461@zippy.cdrom.com> In-Reply-To: Your message of "Mon, 12 Apr 1999 21:22:14 BST." <19990412212213.B9344@catkin.nothing-going-on.org>
index | next in thread | previous in thread | raw e-mail
> 1. Does the Handbook need a 6 month release cycle? The majority of
> the content doesn't change that much in 6 months. Wouldn't a
> threshold of "changes made since last printing" make more sense,
> perhaps with a minimum 6 month wait between prints.
I don't think 6 months is written in stone anywhere, it's probably
just a working figure. I do know that part of the reason for doing
this, as I stated before, is to get the handbook to the point where
it's a going concern and people are actually getting paid to work on
it (since volunteerism has left us with many sections asterisk'd for
years :), and that might entail doing fairly regular releases just to
keep that process going, but I certainly don't think anyone would
demand a reprint if there were no substantially new content either.
> 2. What's the Walnut Creek reaction been to my ideas about splitting
> the Handbook up into smaller books? After "FreeBSD in 21 days"
> gets done that's my next big project. If the Handbook suddenly
> becomes 12 or 15 smaller handbooks in 8 or 9 months time that's
> obviously going to affect whatever they're thinking of.
Well, part of what was desired was a book (or books) to put into the
FreeBSD retail box, and for that the little book model doesn't map so
well. That said, if there's room for a substantial number of small
books which come out of the handbook, so be it. I think we'd do
better with a couple of smaller, more focused guides than we would
with one big giant honking book that's hard to read. That was sort of
the trend in the mid-90's and it appears, thankfully, to be one which
is now in decline as the backlash against 300lb books that contain
mountains of reprinted material (shovel-books) continues to grow.
My main criticism of the handbook has always been that it fails to
obey a consistent, logical style for each section. There would be
absolutely nothing wrong with a 20 section handbook (or more) if each
section were carefully written with the following guidelines:
1. First paragraph must summarize exactly just what it is we're
talking about ("What is DNS?" "What is a web server?" etc).
2. 2nd and following paragraphs should contain quick setup
information (e.g. "cookbook info") for those who just wish
to get through the problem in the shortest period of time.
3. Last past of the section should include in-depth details on
how it actually works and other under-the-hood sort of
information for those who are actually interested in the meat.
That way, you can immediately tell if the section you're in is what
you actually wanted (sometimes section titles are misleading) and,
if you're a beginning user, you can get quick gratification with the
setup information (the approach taken by http://flag.blackened.net/freebsd,
the infamous "FreeBSD for the lazy and hopeless" page). If you're a
power user, on the other hand, you can just skip straight to the end
of the section for the meat which you know will be there. Either
way, it would go a long way towards eliminating one of the #1 complaints
about the handbook, which is that you have to practically read the entire
friggin' thing before you've really strained the last bit of useful
information out of it. Seeing as how it was written by many different
authors and with no "style guide" this is hardly surprising, but it
still is a considerable jolt to move from one section to another and
find that section 1 was written for dummies and section 2 for experts
with nothing in between or general consistency at all.
- Jordan
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?57153.923960461>