1. A few thoughts on documentation
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.
