Why do we write documentation? Silly question. Because we want others to be able to use our program, library function or whatever we have written and made available. But writing documentation is not all there is to it: Documentation must be accessible. If it’s hidden in some non?standard place where the documentation?related tools won’t find it ?? how can it serve its purpose?

• Documentation must be reliable and accurate. There’s nothing more annoying than having program behaviour and documentation disagree. Users will curse you, send you hate mail and throw your work into the bit bucket, with the firm intent to never install anything written by that jerk again.
• The historical and well known way documentation is accessed on UNIX is via the man(1) command. This HOWTO describes what you have to do to write a man page that will be correctly processed by the documentation? related tools. The most important of these tools are man(1), xman(1x), apropos(1), makewhatis(8) and catman(8). Reliability and accuracy of the information are, of course, up to you. But even in this respect you will find some ideas below that help you avoid some common glitches.

How are man pages accessed?
You need to know the precise mechanism for acccessing man pages in order to give your man page the right name and install it in the right place. Each man page should be categorized in a specific section, denoted by a single character. The most common sections under Linux, and their human readable names, are:
Section The human readable name
1 User commands that may be started by everyone.
2 System calls, that is, functions provided by the kernel.
3 Subroutines, that is, library functions.
4 Devices, that is, special files in the /dev directory.
5 File format descriptions, e.g. /etc/passwd.
6 Games, self?explanatory.
7 Miscellaneous, e.g. macro packages, conventions.
8 System administration tools that only root can execute.
9 Another (Linux specific) place for kernel routine documentation.
n (Deprecated) New documentation, that may be moved to a more appropriate section.
o (Deprecated) Old documentation, that may be kept for a grace period.
l (Deprecated) Local documentation referring to this particular system.

Download pdf Linux Man Page Howto