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

[Rob Landley]

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