discuss: Firewall-HOWTO
Subject:
Re: Firewall-HOWTO
From:
Tabatha Marshall ####@####.####
Date:
18 Nov 2003 06:04:49 -0000
Message-Id: <1069135460.2164.84.camel@mysticchild>
On Mon, 2003-11-17 at 09:42, Rodolfo J. Paiz wrote:
> Hmm... I see your point perfectly. In general, I try to explain what I am
> doing as I go along such that the user also learns in the process; however,
> I tend to start from the point of view that this document is about "how to"
> do something, and that both (a) the background knowledge which is
> prerequisite to this howto and (b) the further learning that can be
> undertaken after this howto is completed, are of secondary importance.
There is nothing wrong with taking such an approach. Many HOWTOs are
written to complete specific tasks.
> Is it, then, the traditional view that a HOWTO must also provide some
> measure of background such that the reader can start from little or no
> knowledge, acquire the basics, then execute the task desired? If so, how
> far back should I start? For example, I would like to assume that the
> reader has the following skills:
>
> * some knowledge of RPM package commands
>
> * ability to install and configure a machine with Linux,
> including setting up his/her own networking devices
>
> * ability to connect his/her system to the Internet
> using whatever device/medium the ISP provides
>
> If I have to explain some or all of that, I'll never get done writing my
> own stuff...
Most authors will include a "Prerequisites" section explaining skills or
hardware required to do the task. You can list the above, and provide
additional links there, or point to a "Resources" section for links
where the reader can get additional information on those items.
> At what point is it valid to submit a HOWTO? I will happily keep adding
> material to my documents until they can jump this (rather high) bar, but it
> is certainly going to take a while. I estimate that my first complete draft
> of the Small Netserver HOWTO will be ready in about two weeks, but it won't
> have all of this... not by a long shot. It will, however, contain
> instructions along with a reasonable amount of commentary such that the
> reader will be told what is going on at each step and will understand it.
> Some previous knowledge is required, though.
Your HOWTO probably has to satisfy a small number of criteria to be
considered "complete" but your mileage may vary (in other words,
personal taste). I think the bottom line would be that as long as
you've stated the prerequisites needed, the remainder of the document
should clearly accomplish the task you said it would. Are the sections
complete, or do they leave the reader in the dark? Did you provide
Resources, a copyright and license, a web page where updates of the
document may be found? These are some other smaller things you can
consider when deciding if you're finished. :D
I hope that's a thorough enough answer. If I missed anything, let me
know!
Tab
--
Tabatha Marshall
Web: www.merlinmonroe.com
Linux Documentation Project Review Coordinator (http://www.tldp.org)
Linux Counter Area Manager US:wa (http://counter.li.org)
