Date: Mon, 12 Apr 1999 12:51:45 +0930 From: Greg Lehey <grog@lemis.com> To: FreeBSD Documenters <doc@FreeBSD.org> Cc: "Robert A. Bruce" <rab@cdrom.com> Subject: Publishing the FreeBSD handbook Message-ID: <19990412125145.J2142@lemis.com>
next in thread | raw e-mail | index | archive | help
Walnut Creek are planning to make a printed version of the FreeBSD
handbook. This is something about which Walnut Creek and myself drew
up a contract some years ago, when I first got involved with writing
documentation for FreeBSD, so I'll be heading this particular effort.
I've been looking at the handbook for a while, and have tidied up some
rough edges, as you may have noticed. But basically it's clear that
the handbook isn't really ready for printing in its current form, and
Bob Bruce has agreed to postpone the matter until it can be tidied up
a bit. We're hoping to be able to get it in printable shape by about
August or September, and then he's talking about having a new edition
printed about twice a year, so the handbook would be subjected to a
release cycle similar in nature to the software release.
I've done some thinking about what needs to be done. I've
deliberately held off while the previous discussion about the future
of the handbook, but it now looks as if we haven't come to any
conclusions which would affect my issues. As I see it, in order to
print the handbook, we need to:
1. Remove the "to be written" sections. Maybe there's a style
sheet option which can help here (Nik?). Otherwise it might
make more sense to just comment out these sections and create a
document "to be done" which describes where they are.
2. Update some old and mouldy sections. Some parts are so old as
to be misleading, and if we don't update them we should
eliminate them. If *you* have contributed in the past, now
would be a good time to check over your contribution and
consider whether you should update it.
Of course, if you want to overhaul a contribution you didn't
write, that's a great idea too, though I suppose it would be a
good idea to check with the author first.
3. Add an index, and generally improve the format. I'm planning to
do this myself, but if anybody else wants to join in (or even
take over), I'll be more than happy.
4. Remove some sections for the printed version only. For example,
Bob suggested that most people who want to send core teams
encrypted messages won't copy the key out of the book, they'll
get it online, so we don't need to publish them. I also wonder
whether we really need to publish 37 pages of contributor names
and (possibly incorrect) mail addresses.
5. Where possible, check the published mail addresses and get them
up to date.
There are a couple of things which I think we don't need to do, but
I'm willing to listen to opinions:
1. Don't change the style. Sure, it's a hodgepodge, but that can
be explained, and I don't think that it will concern the target
audience too much. I do wonder about emoticons and such, but a
real style overhaul would be a very difficult job, and I'd
anticipate a number of clashes of viewpoint in the process.
2. Don't change the overall format. I don't like it yet, but it's
an area that Nik has been working on, and I don't want to get in
his way.
This is just a first cut at this. I'd welcome a discussion about what
we should and should not do, but much more I'd welcome some action.
Basically, you have about 4 months to get your changes into the first
edition; now's a good time to start.
Greg
--
See complete headers for address, home page and phone numbers
finger grog@lemis.com for PGP public key
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?19990412125145.J2142>