Kernel Summit 2006: Documentation

2006 Kernel Summit coverage on LWN.net.

The final session on Monday was concerned with documentation. This discussion was led by Michael Kerrisk, Randy Dunlap, and Jonathan Corbet. Your editor started off with a survey of internal kernel API documentation. The in-kernel documentation directory, shipped with the source code, contains much good stuff, but it is disorganized and unmaintained. Some of the treasures to be found there include details on running Java binaries under the 1.3 kernel and a discussion of the trials and tribulations of putting Linux on systems with more than 16MB of memory. The latter states:

Linus stole your editor's punchline by noting that this file clearly contains advice which is still good, so it should be retained.

Other sources of kernel API documentation include books - all of which are currently obsolete. There is also a fair amount of information available on web sites, including this one. A few questions were presented for discussion, but what the developers really wanted to talk about was the tools used to generate the KernelDoc documents. These tools are effective, but very slow, and they lack the ability to express everything of interest about a given interface. Your editor got the impression that, if the KernelDoc tools were improved, much of the documentation problem would simply go away. Who knew it was so easy?

The second half of the session was led by Michael Kerrisk, who has been putting a great deal of time into improving the kernel man pages distribution. These pages are the primary documentation of the kernel user-space API, and they have seen a relatively low level of attention for some time. The networking pages, for example, cover the 2.2 version of the interface.

The man-pages distribution contains over 800 pages. Despite the time that Michael has put in, he is having a hard time keeping up with the changes being made by the kernel developers. The writing work is hard enough on its own, but, even before then, Michael must watch the patch stream and notice that API changes have been made. It would be nice if there were a better way.

Michael talked about various approaches to improving the maintenance of the man pages. These include getting other maintainers to help out (by, at a minimum, calling attention to API changes), paying a writer to do the work, or requiring kernel developers to write man pages for any APIs they add. While the last one might seem like a good idea, Linus made the claim that "a lot of kernel developers have huge problems communicating with humans." Forcing them to write documentation might not be in anybody's best interest.

So the creation of kernel documentation is likely to remain a task performed by a relatively small group of people. OSDL is currently considering a proposal to fund a writer for a fixed period; if that proposal goes through, we may see kernel documentation coming out at a higher rate.

Index entries for this article
Kernel	Documentation

---

to post comments

Kernel Summit 2006: Documentation

Posted Jul 18, 2006 9:18 UTC (Tue) by nix (subscriber, #2304) [Link]

The user-space kernel headers semi-automatically maintained by David Woodhouse may prove useful here. One hopes that a large part of the job of spotting API changes would be done by spying on the commit stream for this project, given that commits only happen when the user-space ABI changes, and that every ABI change should have a corresponding autocommit to this tree.

(Well, every ABI change other than changes in the layout of filesystems such as sysfs...)

Kernel Summit 2006: Documentation

Posted Jul 18, 2006 9:52 UTC (Tue) by smitty_one_each (subscriber, #28989) [Link] (2 responses)

No mention of http://www.kernelnewbies.org/ ?

KernelNewbies

Posted Jul 18, 2006 10:43 UTC (Tue) by corbet (editor, #1) [Link] (1 responses)

I mentioned a number of sites during the session, and KernelNewbies was one of them.

KernelNewbies

Posted Jul 18, 2006 15:25 UTC (Tue) by chrish (guest, #351) [Link]

Could you list the others? I already knew about KernelNewbies. I didn't know that there were other useful sites like it.

Kernel Summit 2006: Documentation

Posted Jul 18, 2006 10:26 UTC (Tue) by kleptog (subscriber, #1183) [Link] (1 responses)

... or requiring kernel developers to write man pages for any APIs they add. While the last one might seem like a good idea, Linus made the claim that "a lot of kernel developers have huge problems communicating with humans." Forcing them to write documentation might not be in anybody's best interest.

Which is why we have people called "editors". The developers don't need to write brilliant documentation. As long as they can succinctly and clearly describe the interface, some time later someone can come along and make it readable for normal people.

agreed

Posted Jul 18, 2006 23:32 UTC (Tue) by ccyoung (guest, #16340) [Link]

this has other advantages as we, namely participation and ownership by a whole new set of people, such as myself, whose C days are long behind.

Kernel Summit 2006: Documentation

Posted Jul 18, 2006 11:17 UTC (Tue) by stijn (subscriber, #570) [Link]

Manual pages .. I hold them dear. In what source format are they generated? I seem to recall they are DocBook manpages. When it comes to sucking out all life and joy DocBook manpages easily beat any quantity of deatheaters. (which, as a mere aside, is why I wrote the somewhat grandiloquently named PUD).

Tracking API changes for manpages

Posted Jul 18, 2006 12:52 UTC (Tue) by cventers (guest, #31465) [Link]

What is needed is a _simple_ ticketing system (ie, not big scary
Bugzilla). When an API will be added or changed, it should be a rule that
the change be filed as a ticket against the affected manpages.

Kernel Summit 2006: Documentation

Posted Jul 20, 2006 4:48 UTC (Thu) by bryce (guest, #16388) [Link]

OSDL is currently considering a proposal to fund a writer for a fixed period

Specifically, it is the Technical Advisory Board (made up of kernel community members) considering the proposal. IIRC, the roadblock presently is receiving funding that was pledged by various companies when the TAB was set up.

Documentation as sanity checking

Posted Jul 23, 2006 13:41 UTC (Sun) by fergal (guest, #602) [Link]

I find documentation to be a great final step in the development of code. I have frequently made improvements to my code (especially to interfaces) as a result of trying to write documentation. If you can't document it easily then it's broken (the truth of this statement varies from domain to domain but I think it's a good first approximation).

Ideally that sort of stuff would be found in my design documentation but I (like many others) am merely mortal and get a bit too excited about bashing out code to write a detailed designed beforehand.