Date: Mon, 16 Mar 1998 07:42:17 -0800 From: "Jordan K. Hubbard" <jkh@time.cdrom.com> To: doc@FreeBSD.ORG Cc: Studded <Studded@dal.net>, FreeBSD-doc@FreeBSD.ORG Subject: Re: Documentation plan? Message-ID: <20353.890062937@time.cdrom.com> In-Reply-To: Your message of "Mon, 16 Mar 1998 15:31:25 GMT." <19980316153125.64380@iii.co.uk>
next in thread | previous in thread | raw e-mail | index | archive | help
> 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. Jordan 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?20353.890062937>