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

Re: [Document Project] OpenBSD Documentation Explained.

I like where you're going, I think that some of our man pages have lots of examples and some don't have so many. If we could get more examples in our man pages that don't have so many, that would be good. I'm not saying we need to make an active effort to do so, but that is one thing that people who wanted to help could do: submit example sections to man pages. Also, here is another idea: what if we add another 'section' of the man pages, like section 9 or something, and make it the 'how-to' section. If you do 'man 9 printing' you would get a how-to on printing. Also, if you do a 'man lpr' then in the list of 'see also' references it could say 'printing(9)'. This way, everything would still be done through the man pages. As for the people who want how-to's on the web, it now just becomes a matter of making the man pages accessible on the web and indexing them and adding a table of contents for the how-to pages. People already have things which allow man pages to be searched/accessed via the web, so if we build on that, it shouldn't be too much of a problem. An idea?


At 01:27 PM 12/7/00, you wrote:
Just to make something clear, OpenBSD is the most user/admin friendly
operating system I've ever used.

I would like to stress to people that are interested to documentation
to take a good look at what is already there, and, if you feel the
need to improve on something, contribute to those areas.  The man pages
are already there and can be searched from the web.  If you feel the
need to contribute something, make it a part of the existing system,
even if you want to call it a howto.  What's important is that I can
type man -k whatever and find it without having to use a web browser
and a search engine.  And even if I am, I can get it from the online
man pages.  Maybe the faq should even be incorporated as a man page
(right now man faq gives you afterboot).

Speaking of afterboot, it is probably one the best pieces of documentation
an operating system every had.  I agree that OpenBSD should be proud
of its documentation efforts.

While sometimes weak on examples, man pages do work.  It is so great with
OpenBSD to be able to read a man page and not have to assume you are
reading a piece of outdated crap (which is what it's like on virtually
every Unix-like OS).

Then let me say that if you make an effort to look in the man pages,
faq, and the mail archive, and you ask something relatively OpenBSD
specific, there is no reason you should be flamed.  If you are, you
probably aren't the one with the problem.

-- Brandin Claar Network Coordinator Penn State Applied Research Lab

Visit your host, monkey.org