[Shorewall-devel] RE: Docs
Fri, 26 Apr 2002 14:50:06 -0700 (PDT)
On Fri, 26 Apr 2002, Ron Shannon wrote:
> All points agreed.
> As you suggest, the docs are better if they're a well-integrated set. If
> a choice is made to exclude an advanced subject or level of detail from
> the QSG, they should be covered elsewhere. As noted before, the docs as
> a whole are exceptionally good. Your extra effort on the docs certainly
> shows and is one of the things that attracted me to Shorewall. Still,
> things like having both a "Quick Start Guide" and a "Getting Started"
> can be confusing. <g>
> A more organized, standard structure for the docs might look more or less like:
> 1) Introduction (Philosophy, Architecture)
> 2) Quick Start Guide (Requirements, Install, Minimum Setup, Sample Configs)
> 3) Administrator's Guide (Detailed Setups, Configs & Functional
> Interactions, Advanced Configs, Admin Scripts...)
> 4) Reference Guide (Detail config file explanations & parameters....)
> 5) Resources (External links to tutorials, standards, other source materials....)
> 6) General Index (comprehensive coverage of at least 1-4 above)
I wonder if we can generate an Index from the Search database - keeping an
index up to date is a PITA.
The above organization sounds ok to me. I've always shyed away from having
both an Administrator's Guide and a Reference Guide because of the amount
of work involved and the possibility of presenting conflicting infomation.
With more people contributing, maybe that won't be as much of a problem.
> How would you feel about a Shorewall-docs list? There is the ever
> present danger of list creep, but if this effort turns out to include
> more fire than smoke it could be useful. I haven't been following the
> devel list until today. Perhaps its subscribers won't mind docs taffic
> and/or it would be sufficient.
The development list has been almost moribund as of late so let's use it.
If list cross-talk becomes a problem, we can always add a new list.
I've added the Development list to the CC for this thread.
Tom Eastep \ Shorewall - iptables made easy
AIM: tmeastep \ http://www.shorewall.net
ICQ: #60745924 \ firstname.lastname@example.org