[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: Another list? (was Linux vs. NT Security contest)

On Wed, 22 Sep 1999, Theo de Raadt wrote:

> > perhaps another mailing list (docs@openbsd.org ?) should be started to
> > discuss man pages, the faq, and other forms of documentation for openbsd.
> > it seems that there is enough interest from people on this list to
> > contribute to the documentation effort (i wouldn't mind contributing,
> > either) that there should be some forum for coordinating the work.
> I'm not sure if a new mailing list will help.  What... more talk?  

i'm not sure a new mailing list will help, either, but i don't think it
would hurt to make one and see how it goes.  if it fails, just abandon it
and continue with the way things are now.

> A few months back I told the mailing list that Aaron and I were doing
> a sort of man page audit, looking for more things to document.  
> Complete and utter silence.  Now it's happening again, and we've
> received one report of something that needs improving.

i think a lot of the things that need to get documented aren't as obvious
to some of us less experienced users.  or we don't speak up because we're
not sure if they're already documented elsewhere.  or we're just not sure
if what we have to say is worth documenting.

> People don't actually want better documentation, that's what I think.

that may be.  it certainly requires less effort on the part of the person
with the problem to just ask a question on the list and hope someone
responds with an answer.  unfortunately, it's a waste of time for the rest
of us when it could easily answered in a faq or man page.  i'd say a
majority of the questions asked on this list get a reply along the lines
of RTFMP or RTFF, though a good number of people just want to know which
FMP to read (sometimes it's obvious, sometimes it's not).

personally, i'm torn on what kind of documentation is appropriate for
openbsd...or rather the people who use it.  people with different
backgrounds look for different kinds of help (duh!).

the people that usually ask the former type of questions are usually
unfamiliar with the whole of the system and are looking for step by step
instructions on how to set up a particular part without messing the rest
of it up.  obviously, it's not worth our time to hand hold every openbsd
newbie, so some sort of set of how-to documents would probably be

on the other hand, i've gotten the impression that the general attitude of
this list is that step by step instructions are frowned upon.  mindlessly
following instructions doesn't really educate the person, it just gets
their system up and running.  when it breaks, they're bound to come
running back to the list and waste our time by asking the same question
the last newbie asked. if they had actually taken the time to read the man
page(s) in the first place, they wouldn't need our help.

i have to agree with some of this; there's nothing more valuable than
doing your homework.  it makes you learn more about what you're working
with...especially what it can and cannot do.  i know i'd certainly have
more faith in someone setting up a firewall on my network at work if they
are actually familiar with the components involved rather than just
mindlessly following a step by step set of instructions. 

however, i think properly done how-to's CAN educate the user about the
system while stepping them through the process.  for example an
explanation could accompany each step.  while this may be somewhat
redundant with information found in some faq, it is readily available to
the user in one document.  while this can become somewhat difficult to
manage, it could probably be easily done by any number of volunteers who
have spoken up already.