Date: Wed, 6 Jan 1999 08:46:18 +1100 From: Sue Blake <sue@welearn.com.au> To: "Jordan K. Hubbard" <jkh@zippy.cdrom.com> Cc: conrads@neosoft.com, doc@FreeBSD.ORG Subject: Re: Kernel configuration docs a neglected area? Message-ID: <19990106084618.64906@welearn.com.au> In-Reply-To: <5637.915555664@zippy.cdrom.com>; from Jordan K. Hubbard on Tue, Jan 05, 1999 at 09:01:04AM -0800 References: <XFMail.990105080414.conrads@neosoft.com> <5637.915555664@zippy.cdrom.com>
next in thread | previous in thread | raw e-mail | index | archive | help
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
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?19990106084618.64906>