Messages in this thread | | | From | "Kevin M. Bealer" <> | Subject | Re: Take A deep Breath - Kernel Documentation | Date | Tue, 22 Jul 1997 23:29:40 -0400 |
| |
Darin Johnson wrote: > > Good, as long as someone other than the coder takes the responsibility > > of maintaining said document. I don't think it's to anyone's benefit to > > delay code changes so that docs can be written. > >That's the wrong attitude. Doc is easy; just don't put it off! The >coder must have that responsibility, because only the coder knows what >changed! It doesn't take much time, but it can take forever if the (clip)
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.
| |