I have nothing whatsoever against coders contributing some or all of
the documentation. I am saying, I think it is wrong to *enforce* it
on them. The system we have -now- is pretty good, certainly better
than enforced documentation.
If the coders document what they think is unclear, then we have the
situation we have now. Someone who "puts their head inside the box"
to write the drivers, usually takes a lot of effort to "take it back
out" while writing the code. One of the biggest problems I have at
work is retracting my brain from the 5+ levels of abstraction to get
back to where the user who doesn't know what a "bit" is, understands
what I am saying. And I am doing -database- programming, with a
database that advertises "power w/o programming" on the cover of the
book (danger will robinson)!
For those who wisely skipped the last paragraph, my point is that the
kernel hackers by and large already commented what they thought was
unclear (not much or the driver wouldn't work). Documentation has to
be written from the point of view of the semi-novice to be read
effectively by said novice.
Whenever I re-write a program, less comments are there, because there
are things that are "obvious" to me that weren't on the first try.
If you don't believe in this type of documentation, don't read it
when/if it comes out... I am heretofore collecting, and anyone who
wants to document (interfaces/subsystems or specific source code
files) or send me suggestions, can send. I will keep it in the same
dir structure as the kernel tarball, and later on it could be merged
if everyone thinks it should.
(Whatever you send me, put a note at the top to the effect that it
is under the GPL. If you don't like idea that tell me why in email.)
I will also put it on my web page if/when any gets here or I write any
myself, and then I will drop the URL here.
People seem divided on this issue, so let's "make dox not war."
--kmb203@psu.edu----------------Debian/GNU--1.3---Linux--2.0.30---
OK, so you're a Ph.D. Just don't touch anything.