From owner-freebsd-doc Tue Jan 5 13:47:35 1999 Return-Path: Received: (from majordom@localhost) by hub.freebsd.org (8.8.8/8.8.8) id NAA14434 for freebsd-doc-outgoing; Tue, 5 Jan 1999 13:47:35 -0800 (PST) (envelope-from owner-freebsd-doc@FreeBSD.ORG) Received: from phoenix.welearn.com.au (welearn.com.au [139.130.44.81] (may be forged)) by hub.freebsd.org (8.8.8/8.8.8) with ESMTP id NAA14413 for ; Tue, 5 Jan 1999 13:47:30 -0800 (PST) (envelope-from sue@phoenix.welearn.com.au) Received: (from sue@localhost) by phoenix.welearn.com.au (8.9.1/8.9.0) id IAA24141; Wed, 6 Jan 1999 08:46:24 +1100 (EST) Message-ID: <19990106084618.64906@welearn.com.au> Date: Wed, 6 Jan 1999 08:46:18 +1100 From: Sue Blake To: "Jordan K. Hubbard" Cc: conrads@neosoft.com, doc@FreeBSD.ORG Subject: Re: Kernel configuration docs a neglected area? References: <5637.915555664@zippy.cdrom.com> Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Mailer: Mutt 0.88e In-Reply-To: <5637.915555664@zippy.cdrom.com>; from Jordan K. Hubbard on Tue, Jan 05, 1999 at 09:01:04AM -0800 Sender: owner-freebsd-doc@FreeBSD.ORG Precedence: bulk X-Loop: FreeBSD.org On Tue, Jan 05, 1999 at 09:01:04AM -0800, Jordan K. Hubbard wrote: > > But you see, that's the problem. I'd gladly help out with this (writing > > that AWE setup tutorial has whet my appetite for doc-writing), but there > > are still too many things in LINT that aren't totally clear to me (I'm sure > > I'm not alone in this), and where to find the needed information is fairly > > mysterious in some cases. > > No mystery at all - UTSL! :-) > > Seriously, the sources are really the only docs for most of this stuff > and *somebody* ends up needing to mine them for information at some > stage in the doc process, so it's not like that's an optional part of > the gig anyway. The authors of each chunk of code (most of whom are > unavailable to us) are usually the least help in this, to be honest, > since all their free time is taken up just in worrying about the > purely technical issues. Also, the best programmers seems to be the > worst at writing docs. :-) For my humble needs, the documentation is adequate and the whole procedure easy to understand. The trouble is that it's really awkward to work through carefully because - The documentation is in three different places (GENERIC, LINT, Handbook) - With those docs and a text editor, this means having four windows in view at once. Pretty hard if X isn't available (yet). - It isn't real easy to read these three docs together because they are structureless and the order of items is different. If this is likely to be the experience of others, I have a simple suggestion that would make it easier without burdening those who update these documents: Divide each document (LINT, GENERIC, Handbook) visually into a number of sections with headings that leap out (rows of ### or something). List these headings at the top of each document. The order of items within these sections can change, but have the sections in the same order within each document, with consistent headings. LINT has been divided up like this a bit, but the headings are not listed at the top and don't coincide with those used in the Handbook. The first section needs a heading. The hardware device configuration section is large enough to get lost in, though it does have subheadings (or are they just comments? are the underlined ones different?). The Handbook splits it up into bit sized chunks, but it's not immediately obvious how to relate them to the actual config files. GENERIC doesn't seem to have any headings, just comments. (ISTR that we need to keep the comment lines in GENERIC to a minumum. Are characters significant or just lines?) The fourth reference, my own kernel's config file, is worse than the lot of them because I've never been encouraged to follow a structure. These changes would make it a lot easier to compare the documents, easier to look for related information in all documents (including new docs if they happen) even when few windows are available, lessen the chance of including one keyword three times because it was encountered at different places/times, make the files look much less intimidating for new users (encourage reading), and give the slowpokes several opportunities to mentally tick off a section, save the file, and take a head-clearing break (or other substance). I'm assuming that the presence of obvious headings, also listed at the top, would be enough to cause those who invent new entries to slot them into the appropriate section without significantly changing the way people work now. Does this seem worthwhile or not? Yeah, yeah, I should send diffs but I don't understand enough to know what belongs together and what to call them without doing more harm than good. If someone sent me a list of headings that would work long term, and a preferred order, I'd have a go at fitting stuff under them consistently for the three documents. Someone more in touch could do a better job though. -- Regards, -*Sue*- To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-doc" in the body of the message