RE: linux-kernel-documentation, proposal

[Linda Walsh]

I problem with requiring documentation -- two fold.  It requires
a thorough understanding of what you just wrote and how it
interacts with the rest of the system and how it is *intended*
to be used.

I'm not sure that everyone who contributes has sufficient grasp of
the 'big' picture to be able to explain that.

There was a rather sensical PhD advisor who wouldn't let any 
candidates advance unless their thesis was written in a way that
an average college graduate (not a specialist in their field) could
understand it.  Actually I think the terms I heard were "average
person on the street", but that may have been a slight exaggeration.

The inability of someone, he felt, to explain it clearly was a reflection
of non-mastery of the subject.  In my own experience I've noticed this
when trying to explain computer concepts to my parents or others
who don't have a technical background.  If I understand something
thoroughly, I can break it down into everyday concepts that are 
understandably by all.  If I don't, I find that I'm relying on some
code jargon that I really don't understand that well but it's how everyone
else talks and maybe no one will ask me to prove that what I just
wrote is actually true or verifiable (as in code verified to do what
it says).

If you never make a clear comment about what the code is supposed to
do, you can't have verification.  Arguments about 'least surprise'
are often subjective (though not always).  The way in which a bug
is fixed can be seen differently depending on what model you used to
conceptualize the code.

The bug fixers aren't always the same as the bug creators.

The 2nd major issue is time.  Having to write documentation myself
at times, I note that it is no where near as 'glamorous' or 'exciting'
of getting that latest new 'gidget-gadget' into the kernel.

Thus while my primary tasks right now are those of Writing and
documenting, I still try to find time on the side to write even
little bits of kernel code (like the LUID patch) that are on the
line toward getting important features like Auditing.  

If only our idea of respecting someone included a basis on how well they 
transmitted their knowlege to others in addition to what they've 
actually done.

-l