Kernel Documentation Fantasy
Posted Nov 27, 2003 2:49 UTC (Thu) by utoddl
In reply to: Kernel Documentation Fantasy
Parent article: Review: Linux Kernel Development
Caveat: I've done very little literate programming -- a couple of toy projects that were one-offs just to see what it looked like. It was fun. It was also a lot of work up front. I'll therefore take your comments at face value and consider that there is a core truth there.
But to your specific points: "Where would the information be that tells you, for example, the lock ordering rules?" Probably in a section or sub-section entitled Lock Ordering Rules, and indexed under "locks" and "rules" and probably a few other ways. Where is the discussion on lock ordering rules now? In some terse comments here and there in the kernel source? No, it's actually scattered about in several years of kerneldev mailing list archives. The hard-fought, well thrashed out issues are important to understand, but their subtle influence on some of the code will be easily lost on the next generation of kernel hackers who try to learn how Linux works by reading only the code and embedded comments, but without those discussions. Old mistakes will be made again and lost lessons relearned the hard way.
About your example digression: Yes, it is wordy. But I think it also advances my knowledge of TeX for the very reasons you cite. It gets across the context that we're about to deal with portability issues that may not be obvious to someone only looking at the code and who's familiar with only one or a few OSs, and only sees a "Danger, Will Robinson" comment with lots of exclamation marks.
:-) Besides, in my Documentation Fantasy, the prose are always perfect, succinct yet engaging, with just the right touch of humor, and they always correct themselves whenever patches are applied. And corbet always checks 'em over in his spare time just to be sure. Hey, as long as I'm dreaming...
to post comments)