[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: Another list? (was Linux vs. NT Security contest)
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 (email@example.com ?) 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.
> however, i think properly done how-to's CAN educate the user about the
> system while stepping them through the process. for example an