From owner-freebsd-doc Mon Mar 16 14:19:23 1998 Return-Path: Received: (from majordom@localhost) by hub.freebsd.org (8.8.8/8.8.8) id OAA12573 for freebsd-doc-outgoing; Mon, 16 Mar 1998 14:19:23 -0800 (PST) (envelope-from owner-freebsd-doc@FreeBSD.ORG) Received: from allegro.lemis.com (allegro.lemis.com [192.109.197.134]) by hub.freebsd.org (8.8.8/8.8.8) with ESMTP id OAA12550 for ; Mon, 16 Mar 1998 14:19:15 -0800 (PST) (envelope-from grog@lemis.com) Received: from freebie.lemis.com (freebie.lemis.com [192.109.197.137]) by allegro.lemis.com (8.8.7/8.8.5) with ESMTP id IAA08115; Tue, 17 Mar 1998 08:48:53 +1030 (CST) Received: (from grog@localhost) by freebie.lemis.com (8.8.8/8.8.7) id IAA28089; Tue, 17 Mar 1998 08:48:47 +1030 (CST) (envelope-from grog) Message-ID: <19980317084847.04060@freebie.lemis.com> Date: Tue, 17 Mar 1998 08:48:47 +1030 From: Greg Lehey To: "Jordan K. Hubbard" Cc: Studded , FreeBSD-doc@FreeBSD.ORG Subject: Re: Documentation plan? References: <19980316153125.64380@iii.co.uk> <20353.890062937@time.cdrom.com> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Mailer: Mutt 0.89i In-Reply-To: <20353.890062937@time.cdrom.com>; from Jordan K. Hubbard on Mon, Mar 16, 1998 at 07:42:17AM -0800 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 On Mon, 16 March 1998 at 7:42:17 -0800, Jordan K. Hubbard wrote: >> Yow. Halt. Slow down. >> >> There's about to be a considerable amount of time and effort invested >> in migrating the Handbook from the LinuxDoc DTD to the DocBook DTD, and >> a large chunk of work has already gone into making sure that this can >> be done without affecting the current content. > > Which is fine and probably a very necessary prerequisite to any such > transition in the future. I also didn't say that the entire baby > should be thrown out with the bathwater, simply that any truly > polished looking Handbook/FAQ/Tutorial combined document is going to > require so much reshuffling that it'd probably be easier to just start > from scratch and slowly bring in pieces from the previous work(s) > until you finally ended up with a wholly new body of work. > > Consider this, for example: Any reasonably well-designed handbook > takes great pains to make each and every logical section map to the > same sort of "skill-set sine wave", e.g. each starts with the basic > concepts, talks about more in-depth concepts towards the middle and > then closes with either the hairy details or (better yet) pointers to > further reading in the "hairy detail section." This way you can leap > to any section in the handbook and know precisely how much if it > you're going to have to read depending on what you want to know. > > The current handbook is nothing like this - each author had different > ideas about how far in-depth to go or at what level to start out with, > resulting in something which plots a lot more like an EEG than a sine > wave on the skill curve. How would you propose to fix that problem > without the literary equivalent of a chain saw? I don't see how. I don't think you can. Trying to impose that sort of discipline on the handbook is equivalent to tell the hackers when to commit their code. It's a volunteer operation, and people will continue to do things their way, frequently with the policy of content over style. I suppose one idea would be to give ownership of specific chapters to people who demonstrate an ability to maintain them. Greg To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-doc" in the body of the message