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

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

On Wed, 22 Sep 1999, alex wrote:

> Can you suggest some specific pages that need work on content?

Do you really want to know? :-)

To start with... The pkg_add man page sucks. Pretend you're a newbie,
start reading it, and try to imagine how confused you'd be. The huge ugly
paragraph at the top should be moved to another section and fixed up a
bit. But basically, someone has to rewrite the page based on information
they glean from playing with pkg_add *thoroughly* and noting all of its
mannerisms and behaviours.

Just about every ipnat/ipf man page is bad except for ipf(8) which I
recently helped re-do.

The rc man pages are unhealthy, especially rc.conf(5). Uhm, afterboot(8)
definitely needs some sort of updating. Surely options(4) does, too.

scsi(8) is completely confusing.

Some man pages need to be moved to a newer format. Not talking different
macros here; but compare the option listings in mixerctl(1), audioctl(1),
and disklabel(8) to most of our pages. They should be fixed.

I started to hack away at the Ethernet driver man pages in section 4 of
the manual but fell way short of the goal. Any of the 3Com man pages (like
xl(4)) should be a good place to start to find out what an Ethernet driver
man page should look like.

There are others, but most people can't do them alone. For example,
boot(8) man pages need to be finished (one for each arch), and there
should also be a bootblock man page for each arch describing its
structure. Section 9 (kernel funcs) still need work. How about, "find all
ioctls in the kernel and make sure they're documented". sysctl(3) needs
work, too.

>From now on I'm saving man page fixes for rainy days. Those people who
don't code can make SIGNIFICANT contributions to OpenBSD by helping to
improve documentation. So get to it!

 :  Aaron Campbell <aaron@cs.dal.ca> - [ http://www.biodome.org/~fx ]