I would like to ask you all to pardon me for a moment while I
gripe just a bit about the paucity of documentation in the NetBSD
project.  I don't mean to be ungrateful, or to load a new task on
the shoulders of already busy and hardworking folks, but frankly
I am surprised that some of the things I mention are not being done
already.  Please take this as constructive criticism, if anything
from someone who has used NetBSD on a daily basis for 2 years or so.

I am not talking about man pages, but about coding style really.
Let me give an example.  Who would guess that the if_eg.c
driver was for the 3C505 board by looking at the sources?
My first recourse is of course the source code, like any real
"hacker" worth his salt.  So, I wander to /usr/src/sys/dev/isa
and grep for the string "505" in the directory with the
network drivers and concluded there was no driver.  Only after I
posted my conclusion and mentioned it would be nice to write a
driver for that board was I informed by someone in the know.
(typing "man eg" does reveal the secret.)

Mind you, when I write a driver for a piece of hardware, I will
put some kind of paragraph sized comment near the start of the
source code. It will contain a description of what the supported
hardware is, how it should be configured, assumptions I made in
writing the driver, known limitations, things I would like to do
to the driver if I ever found the time, and any major wierd features
that gave me headaches. In general I collect information to help myself
at some future date when I have to dive back into my own code,
never mind help some other poor fool that might need to dig into it.
I just can't imagine writing code without making these kinds of notes
in the sources.

I have just paid a visit to the linux world and come away quite
impressed.  I was in their linux/drivers/block directory looking
at support of VLB IDE controllers, and was impressed that the
various drivers all had the sorts of comment blocks just mentioned.
There was a README.ide file that was a goldmine of information,
and while I am on the topic, I need to mention the concept of linux
"HOWTO" files, which are much like little FAQ's on selected topics of
interest.  They are doing a lot of things that we would do well to
emulate.

	Tom
-- 
	Tom Trebisky			Steward Observatory
	ttrebisky@as.arizona.edu	University of Arizona
	(520) 621-5135			Tucson, Arizona 85721