Best practices to put into a man page

Question

Is there a best practices guideline for writing man pages?

What should be included in the layout? The standard ones are:
NAME
SYNOPSIS
DESCRIPTION
EXAMPLES
SEE ALSO

There are others like OPTIONS, AUTHOR.

As a user what would be useful to have? What isn't helpful?

score 4 · Accepted Answer · edited Apr 23 '09 at 02:43

4

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.

edited Apr 23 '09 at 02:43

Jonathan Leffler

730,956
141
904
1,278

answered Apr 23 '09 at 01:51

Brandon Rhodes

83,755
16
106
147

score 1 · Answer 2 · 2009-10-26T04:03:00.193

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.

vezult · Answer 3 · 2009-04-23T01:50:37.710

1

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.

edited Apr 23 '09 at 01:50

answered Apr 23 '09 at 01:43

vezult

5,185
25
41

BUGS is only really needed if there are known bugs. – X-Istence Apr 23 '09 at 01:45
True. Did I really need to supply the if/then logic? – vezult Apr 23 '09 at 01:47
1

EXAMPLES are essential for programs with many different operations, and the man page needs to reflect those. EXAMPLES are often a useful way to do that (see mplayer manual for instance). – hlovdal Dec 01 '10 at 15:56

score 1 · Answer 4 · answered Apr 23 '09 at 01:51

1

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.

answered Apr 23 '09 at 01:51

Charlie Martin

110,348
25
193
263

score 0 · Answer 5 · answered Apr 23 '09 at 01:39

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.

Best practices to put into a man page

5 Answers5