Re: A proposal; making 2.6.20 a bugfix only version.

[Diego Calleja <diegocg@gmail.com>]

El Wed, 08 Nov 2006 23:22:11 +0100,
Arjan van de Ven <arjan@infradead.org> escribió:

> > There are many parts of the kernel that are not documented.
> 
> this is where the OSDL Documentation Person will help a lot; a full time
> person.

Maybe it's just me, but wouldn't be this fixed by just asking developers
to document their code? I maintain the LinuxChanges page at kernelnewbies
and very often I see things merged with zero documentation that I can't
understand even trying to understand the code and I need some googling.
For example, in 2.6.19 there're several "UTS namespace" patches that I
just don't really know exactly what they do...

One of the biggest problems I see when looking at Documentation/ (I
tried to update and fix the sysctl documentation; someone probably feed
me some drugs) is that out-of-code documentation that tries to explain
what the code does, like sysctls, just gets outdated (and that's if the
feature is lucky enought to get documented :) 

The "in-code" documentation using kernel-doc seems to incite developers
to document their code and update it. I think that it should be possible
to document things like sysctls or sysfs. Sysfs really needs something
like that, there's a lot of things in sysfs that aren't documented at all
and the few ones that are documented in Documentation/ are documented
in separated files that _will_ get outdated just like sysctls did. Not
that a "documentation guy" is a bad idea, but I think that getting the
developers envolved in the documentation process would be a better first
step :)