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

[Leif Pedersen <bilbo@hobbiton.org>]

I know that back when I first started using Linux [which was my first
unix], I absolutely hated reading the man pages.  They were very long,
hard to understand, and had very few examples, even when an example was
ALL that was needed.  I got quite discouraged with man pages and seldom
looked at them again for a very long time.  Man pages seem to be geared
towards the experienced users, and I think it should probably stay that
way for four reasons:  1) Man isn't exactly the command you would guess
at for getting help...2) It would be a real pain to rewrite them...3) they
are actually quite useful to more experienced users...4) you have to know
what command you want help on before they're any help at all.

I also remember that when I first started using Linux, the first place I
went to was the web page...I guessed linux.com, linux.org, and
linux.net...and I found HOW-TO's on linux.org.  These explained things
quickly, easily, and by example.  Also, I learned some commands and got an
'entry point' into the man pages.

When I first started using OpenBSD, I once again went to the web page for
docs.  Here I was a little disappointed.  There is a good FAQ, but a
single FAQ isn't quite what I think is needed.  If we had an indexed 
repository of HOW-TO's, or the like, it would be very helpful.


On Wed, 22 Sep 1999, Brahm Windeler wrote:

> 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.

<snip>

> however, i think properly done how-to's CAN educate the user about the
> system while stepping them through the process.  for example an

<snip>