[Shorewall-devel] Docs - QSG & Samples Issues

Ron Shannon
2002-06-06T04:32:33Z

Attached is file "QSG-issues-1.0.txt" containing a numbered and
commented list of issues collected from contributors and recent lists
activity. It might be cool to have these issues in some spiffy issue
tracking system like RT or something, but for a low tech start it''ll
probably suffice.

COMMENTS - IMHO (no particular order):
	I have searched the archives for additional issues/concerns at
some length (read over 200 messages). Most of the search returns
concerned advanced topics probably outside the scope of the QSG and
samples, or were issues that are adequately represented in the attached
list already.
	I created my list (end of the attached) before really reading
through the other contributions. After putting them all together, I was
surprised how much congruence there was in the issues raised by
different people, and agreement as to suggested remedies. In short, most
of the cognitive bumps in the road for one were bumps for many.
	There will always be questions of scope and balance. What
subjects belong in a beginner''s QSG as opposed to file comments or
advanced topics docs, and in what detail? Many issues and comments dance
around those questions.
	The basic docs we''re focusing on now (QSG & samples) are
actually very good. They need maintenance (for currency), some
rearrangement and editing (for clarity), and perhaps some expansion (for
education) -- but they''re pretty darn good. Thanks to Tom''s
very
dedicated work, this doc project starts from a very solid base.

NEXT STAGE SUGGESTIONS:
	Please review the attached file and send any additional issues
you may think of, however small, along with any comments to this list:
mailto:shorewall-devel@shorewall.net. If you were an issue contributor,
please read at least "your" section, as I''ve included
occasional
questions or comments that you might like to address. I''ll try to
continue as maintainer of this issues list, adding things from your
feedback. Perhaps this issues list will go through at least one more
(fairly quick) iteration before a first attempt at rewriting the QSG
begins.
	Next, within the next week or two, those who are interested
could have a chat session and to go over these and any other issues that
come up. After that, one or more people are going to have to blaze ahead
and take a crack at re-writing the QSG itself, incorporating fixes for
the content/presentation/explanation issues. If I''m still standing (new
job project is starting soon) I could make a first attempt at that,
though it would be fine with me if someone else is eager/willing to do
it. Or we could divide up the writing tasks by doc sections, if there''s
a consensus to do that. Concurrently, as Tom had suggested, someone else
should focus on getting the samples up-to-date, clarified, and perhaps
expanded. (Awhile back, Tom volunteered Steve H. for that. Yea!) Any
other suggestions on procedure are welcome, of course.

I''m looking forward to working with everyone as we progress. Thanks a
bunch to all contributors for their thoughtful input so far.

Regards,
Ron