Best practices to put into a man page

Answer 1

It depends on what your software does. If it is a small stand-alone application, I would certainly put the AUTHOR section in the man page so that if users find bugs they can easily find an email address to report the bug to you.

As for best practices, none that I know of, other than that the man page should be concise, detailed but not contain too much information that is not required, if it is just a tool the inner workings are not required for example.

Answer 2

A BUGS section is nice, and an EXAMPLES section is always useful. Some man pages contain a FILES section which lists related configuration files, or ENVIRONMENT section detailing any influential environment variables.

To be clear, what sections or type of information are useful to users depends on the nature of the program or utility that you are documenting.

Answer 3

If you cannot find any old bound copies of 1970s Bell Labs "troff" documentation, which had some nice sections on writing man pages, :-) then I'd suggest trying out Jens's "HOWTO" on writing man pages over at his site.

---

The Unix 7th Edition manuals are available online in a variety of formats.

Answer 4

There is a canonical man page outline distributed with UNIX systems, or at least usually there is. In general, I'd put in all the fields, and include a line like "none" if it doesn't apply.

Answer 5

One thing which people sometimes forget to put in manual pages is the meaning of the return value of the function. It's easy to forget, but the omission can make life much harder for people who have to use your function. Also, a simple code segment in the SYNOPSIS or a good minimal working EXAMPLE is very useful.

One thing that I often do with man pages is to try to find a related command, even though I know the thing I'm looking at doesn't do what I want. In this case, the SEE ALSO is great.