Re: A modest proposal -- We need a patch penguin

Rob Landley
2002-03-01T19:28:49Z

On Monday 25 February 2002 12:13 pm, Randy.Dunlap wrote:
> On Fri, 22 Feb 2002, Hans Reiser wrote:
> | We need to move from discussing whether Linus can scale to whether the
> | Linux Community can scale.
>
> I have to agree with much of what Hans has written here.
>
> and one of the biggest things that would help in this regard, IMHO,
> is to (dare I say "require") provide documentation for kernel
> API changes or semantics. "Read the source" or "Use the source"
> doesn't scale well either, when 10K kernel developers are
> trying to use a new widget in 2.5.4, but they all ask questions
> on lkml about how it's done.
>
> Let's keep Documentation/* stuff up to date. Whether it's in
> text or DocBook format doesn't matter much.
> Or have web pages for it if that's preferred by the project or
> individual(s).

Random comment:

It's design documentation that's needed. Looking at the code you can see
what it's doing, but you sometimes have to read an amazing amount of it to
even guess at WHY... The code doesn't always tell you about the author's
intentions, just the implementation. And sometimes the code is wrong
anyway...

I believe the kernelnewbies project is working on this, but haven't been able
to follow it. (I just moved back to Austin, am recovering from food
poisioning, picking an old job back up... Not following much of anything at
the moment...)

> ~Randy

Rob