Shorewall users - Jan 2003 - Slightly OT: The state of users

Hello all,

I don''t want this to be a tome'' but felt a comment was in
order.

Many new users (Linux and Shorewall are no different) are more apt to not 
read the manual(RTFM) as they view it as "Taking to long" and
don''t
understand it''s relevance in their particular scenario. This is 
unfortunate in the case of Shorewall. As the documents are not only very 
good for the professional (intensively documented on minor revisions), but 
also for the novice - with the examples and "Quick Start" guides. 
Unfortunately, any novice who has tried to read the Prelude and Sendmail 
documentation is liable to forgo reading the Shorewall documentation 
before requesting help. 

So how do we solve this on the list?

The solution is ultimately Tom''s decision, but I would suggest that
maybe
a "Terms" page be sent to a Non-Subscriber posting or to New
Subscribers.
Sympa does this, and I assume MailMan can too. In it, you place the same 
info that Tom has on the Support page. Second, my fellow posters should 
only reply to questions via the list. Many of those who will not help 
themselves don''t even bother to join the list. Hey, they might even
find
their answer while scouring the archives for the responses, right?

In view of the post that started this thought, it was easy to be incensed. 
It was however, easier to take the high road and just ignore it.

Wayne

"That which does not kill me...only postpones the inevitable."
-Despair



()  Join the ASCII ribbon campaign against HTML email 
/\ and Microsoft specific attachments. If I wanted to read HTML, 
    I would have visited your website! Support open standards.

On 14 Jan 2003 at 14:13, admin@kiteflyer.com wrote:
>Unfortunately, any novice who has tried to read the
> Prelude and Sendmail documentation is liable to forgo reading the
> Shorewall documentation before requesting help. 
> 
> So how do we solve this on the list?
One thing that might help is a web page for submitting
questions to the list which would include a check list 
for all the pertainant clues that need to be included in the 
question.

So often Ive seen (and been guilty of) questions that
are missing great chunks of the puzzle, and had these
parts been included, the very act of including them
would have tipped the user to the possible problem.

Adding two of three catch phrases embedded into the quick start
guide which new users are STRONGLY encouraged 
to mention when asking for help will clue us in to who has, 
and who has not, done their homework (not that its always
unobvious).  Deep in the Quick start guide the Name of 
Tom''s favorite BaseBall team could me mentioned.  Starting
your help request with "Hello Mariner Fans:" would gain
you more immediate answers than someone who starts
out saying "It Doesn''t work".

OTOH, there are a fair number of non-trivial questions posted
here too.

______________________________________
John Andersen
NORCOM / Juneau, Alaska
http://www.screenio.com/
(907) 790-3386_______________________________________
John S. Andersen
NORCOM  mailto:JAndersen@norcomsoftware.com
Juneau, Alaska
http://www.screenio.com/

On Tuesday 14 January 2003 03:27 pm, John S. Andersen
wrote:
> Adding two of three catch phrases embedded into the quick start
> guide which new users are STRONGLY encouraged
> to mention when asking for help will clue us in to who has,
> and who has not, done their homework (not that its always
> unobvious).  Deep in the Quick start guide the Name of
> Tom''s favorite BaseBall team could me mentioned.  Starting
> your help request with "Hello Mariner Fans:" would gain
> you more immediate answers than someone who starts
> out saying "It Doesn''t work".
I don''t personally care much for this approach.
To be a bit pedantic, I''ve always felt that the whole point of open
source /
free software was the _community_.  So often we pride ourselves on our 
ability to get answers quickly, and the vast body of knowledge that is 
available via mailing lists and discussion forums.  Making barriers to this 
access is not at all a good move for the community, in my mind.

We''re always going to have people asking dumb questions.  Sometimes
we''ll be
guilty of this ourselves.  Some of the higher traffic mailing lists
I''ve
subscribed to in the past were _filled_ with questions that were fairly well 
answered in the documentation (the Samba mailing list comes to mind), yet 
they rarely devolved into insults or bickering.

Tom has been absolutely amazing in his support on this list.  I don''t
often
participate because I don''t use many of the awesome features of
Shorewall.
As such, I don''t feel qualified to answer the questions even if I think
I
know the answer.  Besides, Tom''s answers are usually coming through
while I''m
typing any such response!  =)  I think if Tom would wait ten minutes after 
receiving every request, it would allow some of us to pick up the slack and 
start supporting each other, thus taking the burden off of Tom.

My own personal preference when answering a question that has a relevant 
portion detailed in the docs is to link to the online documentation and quote 
the important parts in my response.  Not only does this help the person who 
asked the question, and anyone who might be lurking the list, it helps people 
who google for answers later.

--On Tuesday, January 14, 2003 02:13:28 PM +0000 admin@kiteflyer.com wrote:
> Hello all,
>
> I don''t want this to be a tome'' but felt a comment was in
order.
>
> Many new users (Linux and Shorewall are no different) are more apt to not
> read the manual(RTFM) as they view it as "Taking to long" and
don''t
> understand it''s relevance in their particular scenario.
I find that very often the ONLY thing that peope apparently read are:

a) The comments in the config files.
b) The email address of the user''s list.

In my next product, I think that I''m going to avoid any comments
whatsoever
in the config files. They are a pain in the ass to maintain because they 
duplicate the information in the documentation and they are out of date the 
first time that the user updates the product anyway. AND they provide a 
means for people to take a hack at installing the product without knowing a 
thing about what they are doing. We actually see posts that lament
"I''ve
looked over the comments in the config files for days and can''t solve
this
problem...". This is particularly distressing for me since I have several 
times more effort invested in the Shorewall documentation than I have in 
the Shorewall code.

As to the suggestion that we have a checklist for problem submission, there 
has been such a checklist in place since last week and I have yet to notice 
a marked increase in the quality of the problem reports -- Maybe I need to 
embedd the checklist in the comments in the rules file :-)

I think that the fundimental problem is that we have become used to the 
idea that installing software involves inserting a CD and answering a 
couple of mindless questions. And as you point out, the current standard 
for Software Documentation is at an all time low.

-Tom
--
Tom Eastep   \ Shorewall - iptables made easy
Shoreline,    \ http://shorewall.sf.net
Washington USA \ teastep@shorewall.net

--On Tuesday, January 14, 2003 03:45:08 PM -0500 Scott Merrill 
<smerrill@finelinegraphics.com> wrote:
>
> Tom has been absolutely amazing in his support on this list.  I
don''t
> often  participate because I don''t use many of the awesome
features of
> Shorewall.   As such, I don''t feel qualified to answer the
questions even
> if I think I  know the answer.  Besides, Tom''s answers are usually
coming
> through while I''m  typing any such response!  =)  I think if Tom
would
> wait ten minutes after  receiving every request, it would allow some of
> us to pick up the slack and  start supporting each other, thus taking the
> burden off of Tom.
I realize that and I''m REALLY trying to stay in the background now to
let
others answer the day to day questions. If something complex comes up that 
no one is stepping forward on, I''ll get involved.

-Tom
--
Tom Eastep   \ Shorewall - iptables made easy
Shoreline,    \ http://shorewall.sf.net
Washington USA \ teastep@shorewall.net

cheers( Tom and list);

> In my next product, I think that I''m going to avoid any comments
whatsoever
> in the config files. They are a pain in the ass to maintain because they 
> duplicate the information in the documentation [...]
I remember, I asked about all those comments -- especially if the last
line comment is necessary.

Although I like my config files lean and only with the most needed
comments, I really _do_ use those comments. And I in deed looked up some
syntax and options in shorewall config files.


I know, documentation can be really hard and takes a long of time to be
useful. And I thank you for your great firewall and documentation.

> I think that the fundimental problem is that we have become used to the 
> idea that installing software involves inserting a CD and answering a 
> couple of mindless questions. And as you point out, the current standard 
> for Software Documentation is at an all time low.
Yeah, and we all know what company caused this user attitude... ;-)

Everyone administrating a Server / Firewall should know, what he does.
There''s no such thing as a Firewall Software out of the box (and
shouldn''t IMHO). There are black boxes with cables stuck to them out
there to buy...


Tom, hope you are getting better...

 karsten


-- 
Hi, I''m a signature virus. Copy me into your ~/.signature to help me
spread!

On 15 Jan 2003 at 0:02, kb wrote:
> cheers( Tom and list);
> 
> 
> > In my next product, I think that I''m going to avoid any
comments
> > whatsoever in the config files. They are a pain in the ass to
> > maintain because they duplicate the information in the
> > documentation[...]
> 
> I remember, I asked about all those comments -- especially if the
> last line comment is necessary.
> 
> Although I like my config files lean and only with the most needed
> comments, I really _do_ use those comments.
I too VERY MUCH like the comments in the config files, they
save so much thrashing around when you need to look something
up and your firewall is down, or you are three ssh-hops away from
the machine in question etc.

I see Tom''s point about the comments becoming out of date
quickly as the upgrades are applied but the old rulse/policies etc
are retained.

I hope there is some method by which we can have our cake (locally)
and eat it too.  If these MUST go I would hope the actual config 
files could retain an embedded url to both the web doc and to a local 
file system text file describing syntax of each file.  This could be
in /usr/docs/shorewall or wherever the linux police want them,
and could be replaced at will on each new release.

______________________________________
John Andersen
NORCOM / Juneau, Alaska
http://www.screenio.com/
(907) 790-3386_______________________________________
John S. Andersen
NORCOM  mailto:JAndersen@norcomsoftware.com
Juneau, Alaska
http://www.screenio.com/

cheers();

> I hope there is some method by which we can have our cake (locally)
> and eat it too.  If these MUST go I would hope the actual config 
> files could retain an embedded url to both the web doc and to a local 
> file system text file describing syntax of each file.  This could be
> in /usr/docs/shorewall or wherever the linux police want them,
> and could be replaced at will on each new release.
After the first few word from this I had the same idea.

A local documentation (even apart from the config files) would really be
great. At least the QuickStart Guides are very helpful and often needed,
when setting up a new firewall.

Those docs should be in text format (as firewalls don''t need an X
server) and could be converted from the documentation on shorewall.net.

 karsten


-- 
Hi, I''m a signature virus. Copy me into your ~/.signature to help me
spread!

This might be a bit off topic, but the people on this list might have
some good leads.

I am interested in finding a low cost, small, Shorewall capable computer
system.  i want is something about the size of an 8 port switch.  I
don''t
just want a cheap computer because I want to put it near a small workgroup
switch to give the group some protections and I don''t want it to look
like a PC.

Please send me a note if you have some favorite brand of small size
hardware that can run Leaf with Shorewall.

-- 
Steve Herber	herber@thing.com	work: 206-261-0307
Systems Engineer, AMCIS, UoW		home: 425-454-2399

--On Tuesday, January 14, 2003 6:13 PM -0800 Steve Herber 
<herber@thing.com> wrote:
> This might be a bit off topic, but the people on this list might have
> some good leads.
>
> I am interested in finding a low cost, small, Shorewall capable computer
> system.  i want is something about the size of an 8 port switch.  I
don''t
> just want a cheap computer because I want to put it near a small workgroup
> switch to give the group some protections and I don''t want it to
look
> like a PC.
>
> Please send me a note if you have some favorite brand of small size
> hardware that can run Leaf with Shorewall.
>
Steve,

You might post on the Leaf list -- I''ve seen offers of such boxes for
sale
there in the past.

-Tom
--
Tom Eastep   \ Shorewall - iptables made easy
AIM: teastep  \ http://shorewall.sf.net
ICQ: #60745924 \ teastep@shorewall.net

Tom Eastep schrieb:
> 
> --On Tuesday, January 14, 2003 02:13:28 PM +0000 admin@kiteflyer.com wrote:
> 
> > Hello all,
> >
> > I don''t want this to be a tome'' but felt a comment
was in order.
> >
> > Many new users (Linux and Shorewall are no different) are more apt to
not
> > read the manual(RTFM) as they view it as "Taking to long"
and don''t
> > understand it''s relevance in their particular scenario.
> 
> I find that very often the ONLY thing that peope apparently read are:
> 
> a) The comments in the config files.
> b) The email address of the user''s list.
> 
> In my next product, I think that I''m going to avoid any comments
whatsoever
> in the config files. They are a pain in the ass to maintain because they
> duplicate the information in the documentation and they are out of date the
> first time that the user updates the product anyway. AND they provide a
Tom,

Please, don''t remove the comments in the config files. I''m
using them as
a quick reference when doing small changes and they provide almost all
information I usually need. If I don''t find what I''m looking
for in the
comments, it must be something more difficult and I take some time to
read the great shorewall docs. Those who don''t understand what the
comments are good for, they will also not understand what the great
shorewall docs are good for. AND, at least on my boxes, comments are
never out of date after upgrade. I''m using an upgrade script which
maintains comments in config files while upgrading shorewall to the
newest release (yes, I''m using RPM too).

Simon
> means for people to take a hack at installing the product without knowing a
> thing about what they are doing. We actually see posts that lament
"I''ve
> looked over the comments in the config files for days and can''t
solve this
> problem...". This is particularly distressing for me since I have
several
> times more effort invested in the Shorewall documentation than I have in
> the Shorewall code.
> 
> As to the suggestion that we have a checklist for problem submission, there
> has been such a checklist in place since last week and I have yet to notice
> a marked increase in the quality of the problem reports -- Maybe I need to
> embedd the checklist in the comments in the rules file :-)
> 
> I think that the fundimental problem is that we have become used to the
> idea that installing software involves inserting a CD and answering a
> couple of mindless questions. And as you point out, the current standard
> for Software Documentation is at an all time low.
> 
> -Tom
> --
> Tom Eastep   \ Shorewall - iptables made easy
> Shoreline,    \ http://shorewall.sf.net
> Washington USA \ teastep@shorewall.net
> 
> _______________________________________________
> Shorewall-users mailing list
> Shorewall-users@shorewall.net
> http://mail.shorewall.net/mailman/listinfo/shorewall-users

On Wed, 15 Jan 2003, Simon Matter wrote:
> Please, don''t remove the comments in the config files.
I''m using them as
While the comments in the config file are helpful the "cost" of
maintaining them and the documentation is excessive.  This is especially
true when you consider how much Tom is being paid for his work.  :-)

I admit to having used them as a "cruch" but I also think I''d
learn more
without them.  I feel people learn more by doing than by just following
someone''s examples.

Now, that shouldn''t stop someone contributing config files with
comments.
Maybe that is what this web site needs....a "Contributor''s
Area"?

Ed

On Tue, 2003-01-14 at 18:13, Steve Herber wrote:
> This might be a bit off topic, but the people on this list might have
> some good leads.
> 
> I am interested in finding a low cost, small, Shorewall capable computer
> system.  i want is something about the size of an 8 port switch.  I
don''t
> just want a cheap computer because I want to put it near a small workgroup
> switch to give the group some protections and I don''t want it to
look
> like a PC.
> 
> Please send me a note if you have some favorite brand of small size
> hardware that can run Leaf with Shorewall.
Steve,
There is a list of hardware links here:
http://leaf-project.org/links.php?op=viewlink&cid=8

-- 
Mike Noyes <mhnoyes @ users.sourceforge.net>
http://sourceforge.net/users/mhnoyes/
http://leaf-project.org/  http://sitedocs.sf.net/  http://ffl.sf.net/