Notes on clarifying man pages

It’s striking that all the examples in this blog post are man pages for big sprawling complicated programs – but not surprising, because they are the programs most in need of clarification, and they are the programs that ~jvns does such a great job of explaining to us all. However I’m often disappointed by man pages for a small programs.

There are a few rules of thumb that make short man pages much better.

• Use the roff mdoc macros: it’s hard to find a better semantic markup system that can produce good man pages.
• The “for authors” documentation for the mandoc tools (and the similar documentation for groff) has lots of wisdom.
• Build the man page around a definition list with a heading for each option.
• Fill out the unloved sections like FILES and ENVIRONMENT and SEE ALSO.
• “Don’t repeat yourself” is a mistake in documentation: your users are going to parachute in, trying to find out what an option or file or environment variable does without having read any conceptual overview. They want the description of that option (etc) to explain everything they need to know about it, or refer to other parts of the documentation they need to read.
• Cross-reference as much as possible.
• Assume your users won’t read the OVERVIEW.
• They will look at the EXAMPLES, so use the examples to illustrate the main points in the overview, and explain what each example is doing in detail, even though the explanation repeats what is said in the overview or in the description of the options used by the example.

An old antipattern which I am happy to see is becoming rarer is the wall of text: paragraphs of prose that explain the program in discursive fashion. The worst cases bury the options mid-paragraph, and might even spread the description of an option across multiple paragraphs interspersed with other more-or-less related options. My first contributions to BIND, many years ago, were rewrites of the worst man pages to change walls of text into a structured reference :-)

One of the things I dislike about the GNU coreutils info style is that it combines the worst features of a bad list of options and a wall of text. A list of options with a terse summary of each option is OK as output from --help, but in a man page the list of options should have a complete explanation for each option right there. The explanations should not be deferred to a wall of text below a terse list of options.

It’s best if the options are described in alphabetical order in the main reference. It’s very difficult to order them by function or purpose as the primary key, and that classification is rarely useful for the reader. (The GNU info documentation tries to do this, which makes it much harder for me to find where an option is described.) If the alphabetical list is unwieldy, add secondary lists of options classified by how they are used. Include an option in multiple classifications if that makes sense. In short man pages for small programs, cross-references between options are usually enough that it isn’t necessary to classify the options.