Date: Tue, 17 Mar 1998 08:48:47 +1030 From: Greg Lehey <grog@lemis.com> To: "Jordan K. Hubbard" <jkh@time.cdrom.com> Cc: Studded <Studded@dal.net>, FreeBSD-doc@FreeBSD.ORG Subject: Re: Documentation plan? Message-ID: <19980317084847.04060@freebie.lemis.com> In-Reply-To: <20353.890062937@time.cdrom.com>; from Jordan K. Hubbard on Mon, Mar 16, 1998 at 07:42:17AM -0800 References: <19980316153125.64380@iii.co.uk> <20353.890062937@time.cdrom.com>
next in thread | previous in thread | raw e-mail | index | archive | help
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
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?19980317084847.04060>