From owner-freebsd-doc Sun Apr 11 20:24:21 1999 Delivered-To: freebsd-doc@freebsd.org Received: from allegro.lemis.com (allegro.lemis.com [192.109.197.134]) by hub.freebsd.org (Postfix) with ESMTP id C42B4151F3 for ; Sun, 11 Apr 1999 20:24:15 -0700 (PDT) (envelope-from grog@freebie.lemis.com) Received: from freebie.lemis.com (freebie.lemis.com [192.109.197.137]) by allegro.lemis.com (8.9.1/8.9.0) with ESMTP id MAA08116; Mon, 12 Apr 1999 12:51:51 +0930 (CST) Received: (from grog@localhost) by freebie.lemis.com (8.9.3/8.9.0) id MAA69352; Mon, 12 Apr 1999 12:51:46 +0930 (CST) Message-ID: <19990412125145.J2142@lemis.com> Date: Mon, 12 Apr 1999 12:51:45 +0930 From: Greg Lehey To: FreeBSD Documenters Cc: "Robert A. Bruce" Subject: Publishing the FreeBSD handbook Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Mailer: Mutt 0.93.2i WWW-Home-Page: http://www.lemis.com/~grog Organization: LEMIS, PO Box 460, Echunga SA 5153, Australia Phone: +61-8-8388-8286 Fax: +61-8-8388-8725 Mobile: +61-41-739-7062 Sender: owner-freebsd-doc@FreeBSD.ORG Precedence: bulk X-Loop: FreeBSD.org 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