Re: kernel documentation is bad

Michael L. Galbraith (mikeg@weiden.de)
Tue, 22 Jul 1997 20:57:12 +0200 (MET DST)


On Mon, 21 Jul 1997, Keith Rohrer wrote:

> And lo, Michael L. Galbraith saith unto me:

cute.. I take it you took offense. That's ok.. I did too.

> > > > If we forced documentation rules, this would kill kernel developement like
> > > > nothing else. If you worry about docs, you arent going to bother molding
> > > > and shifting the code.
> > > Forced documentation rules are one thing. Not documenting a major
> [snip]
> > I don't like that 'F' word.. you both used it as if it were an option.
> I don't like it either, and know better than to think it's a real option.
>
> > If this thread manages to resolve the PM issues (valid), it'll be in every
> > PM text in every university in world.
> PM? Patch Management? Provocative Maintenance? Post Meridean?
>

Project Management.. though patch management does have a nice ring to it.

> > I'd rather be trying to figure out the next cool patch.
> I'd rather, when trying to figure out the next cool patch, not having to
> sweat how to hook it into Linux and figure out by brute force what the
> undocumented code isn't telling me that nonetheless breaks my cool patch.
> That is the point of good documentation of the internals: giving the
> generally competent masses the power to fix and add things correctly,
> without having to resort to blood sacrifice to be able to understand
> what they're fixing or interfacing with.
>

Learning to 'hook it into Linux' doesn't take most folks very long.
Unfortunately, understanding what you're 'hooking in' does.

> And if you do come up with a "cool" patch but can't be bothered to document
> it yourself, why should the developers and maintainers waste their time
> figuring out what you're doing and why before evaluating its correctness
> and suitability for inclusion in the main distribution (or why should they
> trust you to know what you're doing when you can't be bothered to write
> code that shows it), when they could be working on "cool" patches
> themselves?
>
> Keith
>

For some reason, I can't really recall this being some kind of problem. Yes,
sometimes someone submits a patch with does esoteric things. The folks who
integrate these patches into the kernel either understand it or they ask
the author. They don't need you or me to 'evaluate' the work involved.

I'm all for documentation. If you can generate some, I'll be sure to read it.
In the mean time, those comments are quite alluring thank you very much.

You'll have to excuse me now, I have to get back to doing it the hard way.

-Mike