[Shorewall-devel] RE: Docs

Tom Eastep teastep@shorewall.net
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>
>

Nod.
 
> 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
-- 
Tom Eastep    \ Shorewall - iptables made easy
AIM: tmeastep  \ http://www.shorewall.net
ICQ: #60745924  \ teastep@shorewall.net