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

RE: [Document Project] OpenBSD Documentation Explained.

What I often do is start "xman -notopbox -bothshown", (which I have
pre-set in an icon in the WindowMaker dock)

This let's me "browse" the lists of manpages.
If I need admin, I look in section 8
If I need a regular command, I look in section 1
If I'm looking for config file formats I look in section 5

This allows me to follow up man -k with more meat.

Now with NeXTSTEP, there was a very nice librarian, (sort of like
Sherlock) which indexed and searched man-pages and other documentation.
It was very good, and once I get GNUstep running, there's a GNUstep
clone that I intend to use.  This indexing is the real problem with man,
not the use of man pages themselves.


The other problem with Manpages is that most newer software for Linux
(which means all new unix software, sadly) follows this "HOWTO"
approach, and don't bother to make manpages.  It's very very
frustrating.  Or they use GNU info, which is unbearable. -cg

-----Original Message-----
From: owner-misc_(_at_)_openbsd_(_dot_)_org [mailto:owner-misc_(_at_)_openbsd_(_dot_)_org]On Behalf Of
Bob Washburne
Sent: Thursday, December 07, 2000 12:04 PM
To: misc_(_at_)_openbsd_(_dot_)_org
Subject: Re: [Document Project] OpenBSD Documentation Explained.

> >       A question, does any document project started for OpenBSD ?
> No, assuming that you mean documentation besides the excellent man
> and FAQ that the OpenBSD developers have provided.
> > If not, why ?
> Because the man pages are so good.

And, unfortuneately, that is what we are stuck with.  Any attempt to
correct the situation with be strongly opposed.

Here is how you learn about OpenBSD:

1) Pretend (or realize) that you are in Academia and that your time is
not worth anything.  The business world may want to just get the answer
and get on with their work, but here you must spend time learning about
the whole system.
2) Read the FAQ. Thoroughly.  Hanging on every word as if you were going
to be tested.  There is a three word phrase hidden in there somewhere
which points to your answer.
3) Find and follow all references to man pages.  Read them thoroughly,
hanging on every word...
4) Eventually you will find the answer to your question.  The man pages
are quite good, meaning thorough, and all the information is out there.
There just isn't any good pointer to it.  (Yes, there is always "man
-k".  And that has actually helped me in about 20% of the times I have
used it.  That is better than the near 0% for commercial Unix's, but
still not good.  Your milage WILL vary.)
5) Just accept the fact the OpenBSD is not user-friendly.  Or even
admin-friendly.  It is written by developers for developers.  It is
excellent stuff and you are free to use it, but you are responcible for
figgureing it out.

The problem with man pages is that you have to know that they exist.
Typicly, you have a problem with the network, printer, etc.  You have a
well formed question, but you aren't familiar with the commands or
subsystems involved.  So what do you do a "man" on?  man -k?  See above.

The beauty of the Linux Howto's is that they provide a
knowlede-prerequisite-free starting point.  You can quickly scan the
list of Howto's and easily find one which addresses your concern;
network, printing, etc.  The Howto then gives an overview of the
subsystem and reffers to different commands, subsystems, etc. which you
can now do a "man" on (you couldn't before because you didn't know they

The other advantage of Howto's is that they provide a forum for
tutorials which might be inappropriate to a man page.  Much of this is
done by the FAQ which is why it is so large.  In fact, each chapter of
the FAQ could be conciddered a Howto.

No such indexed entry point exists for OpenBSD.  You must magicly know
that your answer exists within a certain man page.

To be fair, the developers realized the need for certain overview
documents and so they wrote the FAQ as well as the afterboot and install
man pages.  You just have to know to look for them.

What might help would be simply better advertising for the FAQ.  "Start
By Reading the FAQ and Intall" in large font on the CD and web site.  I
am usually quite good at reading every piece of documentation which
comes my way (I even read the instructions for how to assemble my kid's
toys), but when I first got OpenBSD 2.5 it took me quite a while to
figgure out that these files existed and that they were important.

Hope this helps.

Bob Washburne

Visit your host, monkey.org