L> The 2nd major issue is time. Having to write documentation
L> myself at times, I note that it is no where near as 'glamorous'
L> or 'exciting' of getting that latest new 'gidget-gadget' into
L> the kernel.
Hey! I resemble that remark!
Seriously, if you look around places like the LDP, you will find that
writing good docs is every bit as glamourous, maybe more so, and done
right, is maybe not the thrill of a new fs hack, but it's worth
the effort. Just look at the body of work by Eric Raymond.
Writing technical documentation, in the sense of creating a cohesive
tutorial, is not for everyone, but _documentation_, in the sense of
documenting your own code, should be. I think what Alan and Tim
have started with the GNOME-style comments should be adopted by
all kernel programmers; if every programmer added just one comment
to one public function in their domain every day, we'd have Alan's
"one button 'make book'" in no time.
We don't need engineers writing books, or even chapters, we just need
a little more literate programming. People like me are honoured to
pick up the fragments and do the coallating just to be a part of
Linux. What we need, though, are the fragments. I welcome any and
all napkin/corner-of-envelope diagrams (pls fax to 01-519-4222723 ;)
If everyone working in the code would just add _brief_
what-it-do/what-it-don't GNOME comments, we can assemble enough docs
to put the IBM RedBooks to shame (ok, maybe not), and we can keep
those docs _current_.
L> If only our idea of respecting someone included a basis on how
L> well they transmitted their knowlege to others in addition to
L> what they've actually done.
Again, if we look around, we see ESR and RMS known by more people for
what they have said in print than the wonders they have done in code
(although they themselves are probably more satisfied with the
coding). Quick, can you name 5 programs by ESR? Can you name 5 print
articles?
-- Gary Lawrence Murphy <garym@linux.ca>: office voice/fax: 01 519 4222723 T(C)Inc Business Innovations through Open Source http://www.teledyn.com M:I-3 - Documenting the Linux kernel: http://kernelbook.sourceforge.net Free Internet for a Free O/S? - http://www.teledyn.com/products/FreeWWW- To unsubscribe from this list: send the line "unsubscribe linux-kernel" in the body of a message to majordomo@vger.rutgers.edu Please read the FAQ at http://www.tux.org/lkml/