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

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



Brahm Windeler wrote:

> <snip>

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

> -brahm

I was really glad to see this post, because I had started to write one
myself to
say essentially the same thing, but couldn't formulate my ideas clearly
enough.
Thanks for saving me the trouble! ;)

I think one reason there are so many questions on this list that could
have been
answered with a brief look at the appropriate man page is that there are
many of
us who had bad experiences on other systems with poorly written, out of
date, or
otherwise just plain useless man pages.  The OpenBSD man pages contain
so much
more good information than other systems' pages that is often overlooked
because
people don't expect to find the answers to detailed questions.  One easy
example
is the ppp(8) page.  On other systems, I would expect the page to only
cover the
command line options of the ppp command itself.  The OBSD man page
instead
includes easy to read descriptions of components of the entire system
and their
implications.  On Linux, I would have expected to find this sort of
information
in a HOW-TO or some other part of the LDP.  On other UN*X systems such
as DG/UX,
I wouldn't have expected it to exist at all.

The other good source of information that I think often goes unused is
the source
itself.  The explanation here, I think, is that it's hard to know where
to start
looking if you're not yet intimately familiar with the system.
Especially on
hardware problems, though, which many newbies encounter when trying to
install
the system, and thus are not yet familiar with it, there is valuable
information
which can be had by browsing the source for clues.   The kind of problem
I'm
thinking of is one I had myself with a single EtherExpress 16.  By
reading the
source I found that its io memory had to start between CC000 and D8000,
or else
it wouldn't be detected.  Not the kind of problem that's easy to
document, but
easy to solve once you know where to look in the source.  It was hunting
through
the souce for the ie driver that took most of my time.

Thus, my two suggestions for documentation would not be best suited by
man pages
at all.  They are:

An OpenBSD newbie's general guide to documentation -- Where to find the
answer to
specific kinds of questions.  Including multiple instances of the
sentance, "Read
the FAQ" and a kind of meta-index to the layout and organization of the
man
pages.  I realize that a lot of this is covered by the actual FAQ, the
install
text, and the online man page search engine, so I guess what I'm getting
at is a
document with more newbie friendly language and more syntactical
signposts to
help point them in the right direction.

A Guide to the OpenBSD system source - What subsystems are where, and so
forth.
Not that browsing the code is for everyone, but if you're going to try,
it's a
steep learning curve to start doing anything.

I would be more than happy to help with some form of the former, but I'm
going to
be pretty useless on the latter.