LinuxConf.Au: Do man-pages matter?
The Linux man-pages project, started in 1993, produces sections 2, 3, 4, 5, and 7 of the Linux manual pages. Do these man pages matter? And who do they matter to?
The traditional audience for man pages is usually considered to be userland programmers, and most of them would probably say man pages matter. But what about kernel developers? One kernel-developer response goes like this: "Documentation is fantasy: you have to read the source code to know the truth.”
But man pages matter for kernel developers too, and helping to make man pages better is of direct benefit to kernel developers. I'll show actual examples of how writing or helping someone to write manual pages early in the development of a new kernel feature or interface:
- encourages more and earlier testing of the interface
- leads to fewer bugs in the released interface (too many kernel-userland interfaces are released with bugs!); and
- can result in better designed and more consistent API designs.
I will also look at various ways in which man-pages need to be improved, and consider various reasons why maintaining man-pages is hard.
Discussion is warmly welcomed.