discuss: Additional sections (was: Re: Firewall-HOWTO)
Subject:
Re: Additional sections (was: Re: Firewall-HOWTO)
From:
David Lawyer ####@####.####
Date:
25 Nov 2003 07:25:37 -0000
Message-Id: <20031125065200.GE738@lafn.org>
On Thu, Nov 20, 2003 at 02:40:48PM -0800, Tabatha Marshall wrote:
> On Wed, 2003-11-19 at 11:00, Machtelt Garrels wrote:
> > Somebody talked about having a sort of required prereqs section to each
> > document, and then Terrence came up with the idea of an "I want more"
> > section as well.
> >
> > Tabatha, this might be something to put on your list? I think each
> > document should have both sections in some form, in so far as it is
> > possible. This will also link our TLDP collection together in a better
> > way.
I don't think that a prerequisites section is needed for most documents.
For example, some of the best textbooks on computers have no
prerequisites section. And if books don't need them, the small articles
on LDP shouldn't need them either. Furthermore, if one is online (or
can readily get online), it's easy to look up info online to help
understand things.
Prerequisites can't often be well defined. To fully understand an
article and all of it's implications, one needs one set of prerequisites,
but to just understand enough to "get by" implies a different set of
prerequisites. For example, if I refer someone to "kernel documentation"
do they need to know what the "kernel" is? It's best if they do, but it
may not be really essential. And many HOWTOs are not read from start to
finish. Many people only use a portion of it, for which the
prerequisites are different that for the entire HOWTO.
But for some cases, mentioning prerequisites is a good idea if it can be
done briefly. But in many cases it isn't necessary. For example take
"Serial-Programming-HOWTO". It doesn't need to say that knowing C is a
prerequisite. It's clear from the title that you need to know programming
and if you know programming, you should know that most of Linux is
written in C. This also becomes obvious when one looks at the code.
>
> I liked that idea too, and I'm cc'ing this to the reviewers. Let's look
> out for these, and recommend them in the documentation. There may some
> cases where these might not be useful, but in the majority of HOWTOs and
> Guides, I think this can make an author's documentation more robust,
> therefore more valuable to readers.
I don't agree for the case of prerequisites.
David Lawyer
