LinuxConf Europe 2007

Photos and reports

Timetable

Programme

Registration

LPI Exams

Conference Dinner (Sunday)

Duxford Excursion (Monday)

Exhibitors and Sponsors

Accommodation

Venue

Travel

About Cambridge

Kernel Summit 2007

Other GUUG events

Other UKUUG events

Michael Kerrisk - Google

What we lose without words

Engineers typically like to write code, not words, and when (if!) documentation is written, it is usually regarded as something intended only for users of their software. However, there is one place where documentation, or its absence, matters at least as much to developers as to users: the documentation of interfaces. Interfaces are special, because they are long-term, hard-to-break contracts between developers and their users (i.e., other developers). This makes interface design (and its documentation) critically important, since everyone has to live with the consequences of design decisions for a long time.

Linux kernel developers are typical in that few of them like to write manual pages.

This presentation looks at why the kernel-userland interface documentation provided by the man-pages project (which provides manual page sections 2, 3, 4, 5, and 7) can be as important to them as it is to application programmers. I will show specific examples of how writing and maintaining manual pages forms an important part of good kernel-userland interface design, since: it allows interface designs to be critiqued and improved; it provides an opportunity to achieve greater consistency in design; and it provides a contract that can be used for testing whether a developer's implementation matches their intention.

I will also consider some unfortunate examples of where kernel-userland interface design has gone wrong, or the resulting implementation has been buggy, probably for want of better (or any) documentation during design and implementation. One of the questions to consider is whether kernel developers would themselves benefit from working to improve the documentation in the man-pages project.