JL> I restate my point here (incase you missed it:) Documenting
JL> the kernel is much more important than documenting the
JL> configuration. (besides, as I recall from reading c.o.l.a,
JL> someone already did a kernel config helper.)
More people are likely to be confused by the configuration of Linux
than by its internals. If you want to make Linux the most user
friendly possible, you have to provide the simplest configuration
interface possible.
JL> Why should I bang my head against the wall reading C source
JL> code and trying to understand it well enough to form english
JL> language descriptions, when the authors _already_ understand
JL> it, and could have done the job? That would be a waste of my
JL> time, or it would be something for which I should get paid.
It's like the Bible, the Coran, the Talmud, the Upanishads: you must
read over and over until you attain enlightenment. :-) It is normal to
feel disoriented when you first try to find your way in the code of a
project for the first time. Eventually, you begin to see the big
picture and you can find your way around in no time. The same is true
in understanding the code. At first, it can take some time but you
eventually begin to see patterns emerging.
JL> Writing commentary is not fun as it is, without having to do
JL> the underlying research as well. For me, writing commentary on
JL> K&R format code is impossible, because it is impossible for me
JL> to follow without thouroughly reformatting the code.
This is a problem. You should be able to read _any_ kind of C code.
Documented code in OSes are the exception to the rule and they all use
different coding style, beleive me. Another usefull skill is being
able to write code in any style. If you submit code for Linux in
Emacs formating default (2 spaces for idents), you are likely to upset
the other developpers that will have to use your code because Linux
code is usually formated with hard tabs. If you submit code formated
with vi (hard tabs) for a project that uses Emacs default (spaces),
you are likely to upset the other developpers. You should adapt your
style to the style used for the project. (Fortunately, it's easy to
do for XEmacs users.)
JL> Say... I just had a flash... give the kernel to students in an
JL> operating systems class, and get them to do it. They get
JL> experience in doing the research and writing the
JL> comments. They get a grade from their instructor, and possibly
JL> some email from us. Everyone gets the comments. (Any operating
JL> systems teachers out there willing to do this?)
Before trying to interpret the meaning the code, they have to
understand what an OS is. It usually takes all the time in the course
to explain this to them.
ldd