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.
Yeah, having alphabetical list is the way to go, it's super hard to try to find some option and what it is good for if the program takes many options and have them in sections. It's not like you can search for "a" and hope to hit what -a does for a program with tons of options.
This just.. never works, unless I'm extremely unlucky whenever I try to use man pages.
prose in DESCRIPTION, EXAMPLES etc. also matches "you can use -a in this context"
SYNOPSIS, EXAMPLES can include this option like tool -a -b -c (sometimes you're lucky to avoid this if the example uses tool -bca)
some programs use single dashes for long form opts too, find for example (maybe "long form" is the wrong term, sorry)
depending on your PAGER, searching for -a can match -A (smart case searching etc.)
the CLI is constructed so that the -a flag only applies on a subcommand (man git vs man git log etc.)
and probably many more (sure, PEBKAC too).
All of these are amplified for really long man pages (many search results to skip) or tools with many similar flags (if you're looking for "long form" flags, --a can point you to the first of many flags that uses the same prefix).
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.
When a manpage doesn't include examples it almost defeats the purpose for me.
If you don't like the GNU coreutils info style, the uutils coreutils (a Rust rewrite) manuals combine badly-formatted option lists with random missing bits. They're not even good enough to call utter crap.
Let’s share good role models, like Julia requested. My starting point was to imitate the BSD man pages. POSIX is a mixed bag: it’s thorough, it has reasonably good cross-referencing, it makes effective use of classic man page structure; but the audience for POSIX is implementers not users, so it talks about things like what an implementation is or is not required to do in stilted standardese, without enough examples.
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.
I agree with everything except this. yt-dlp's manpage has example of doing it just right, for a project with a hefty complexity. I find it much easier for day to day usage. Another great example is rg
yt-dlp is an example of what I dislike: What determines the order of options within each section? How do they choose which section to put an option in when it could be in more than one?
My reason for preferring alphabetical order is related to the purpose of that part of the documentation: in Diátaxis terms the main list of options is reference documentation; how the options are classified is explanatory documentation. This kind of thing is a good example of when it’s better to repeat a point, in different styles in different sections of the documentation that serve different purposes.
Personally I only use man pages when I want the "reference documentation" – that is, I already know what option or topic I'm looking for and I just want the full details from an "authoritative" source (also, I'm sufficiently certain that the man page will actually contain this reference doc, and I'm sufficiently certain I can find my option/topic with a string search and don't need fuzzy searching).
But in way more cases I am not primarily looking to learn about a tool but want to solve a concrete problem, regardless of which tool I use. That's why I'm mostly googling for help, rather than reading man pages. And Google usually shows (or used to show) Stackoverflow posts, which usually contain a good answer.
So, half-serious suggestion: look for the most-viewed questions on Stackoverflow regarding the tool you're writing a man page for, and then put these questions and some good answers near the top of the man page?
fanf | 21 hours ago
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.
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.
IcePic | 15 hours ago
Yeah, having alphabetical list is the way to go, it's super hard to try to find some option and what it is good for if the program takes many options and have them in sections. It's not like you can search for "a" and hope to hit what -a does for a program with tons of options.
kwas | 12 hours ago
Erm, you can search for '
-a' (there's a space here), no?iamnearlythere | 8 hours ago
This just.. never works, unless I'm extremely unlucky whenever I try to use man pages.
tool -a -b -c(sometimes you're lucky to avoid this if the example usestool -bca)findfor example (maybe "long form" is the wrong term, sorry)-acan match-A(smart case searching etc.)-aflag only applies on a subcommand (man gitvsman git logetc.)and probably many more (sure, PEBKAC too).
All of these are amplified for really long man pages (many search results to skip) or tools with many similar flags (if you're looking for "long form" flags,
--acan point you to the first of many flags that uses the same prefix).erock | 7 hours ago
When a manpage doesn't include examples it almost defeats the purpose for me.
scruss | 19 hours ago
If you don't like the GNU coreutils info style, the uutils coreutils (a Rust rewrite) manuals combine badly-formatted option lists with random missing bits. They're not even good enough to call utter crap.
fanf | 19 hours ago
Let’s share good role models, like Julia requested. My starting point was to imitate the BSD man pages. POSIX is a mixed bag: it’s thorough, it has reasonably good cross-referencing, it makes effective use of classic man page structure; but the audience for POSIX is implementers not users, so it talks about things like what an implementation is or is not required to do in stilted standardese, without enough examples.
alper | 12 hours ago
Like tail?
kwas | 12 hours ago
I agree with everything except this.
yt-dlp's manpage has example of doing it just right, for a project with a hefty complexity. I find it much easier for day to day usage. Another great example isrgfanf | 5 hours ago
yt-dlp is an example of what I dislike: What determines the order of options within each section? How do they choose which section to put an option in when it could be in more than one?
My reason for preferring alphabetical order is related to the purpose of that part of the documentation: in Diátaxis terms the main list of options is reference documentation; how the options are classified is explanatory documentation. This kind of thing is a good example of when it’s better to repeat a point, in different styles in different sections of the documentation that serve different purposes.
aphaelion | 6 hours ago
This reminded me of tldr, which has been relatively helpful for "larger" tools and is community driven as well, iirc.
https://github.com/tldr-pages/tldr
ThomasAdam | 4 hours ago
Heh. I couldn't agree more.
I've known for some time that fvwm's man page could do with a lot of TLC. Although it has been split up, it's still a wall of text:
https://www.fvwm.org/Man/fvwm3all/
oger | 3 hours ago
Personally I only use man pages when I want the "reference documentation" – that is, I already know what option or topic I'm looking for and I just want the full details from an "authoritative" source (also, I'm sufficiently certain that the man page will actually contain this reference doc, and I'm sufficiently certain I can find my option/topic with a string search and don't need fuzzy searching).
But in way more cases I am not primarily looking to learn about a tool but want to solve a concrete problem, regardless of which tool I use. That's why I'm mostly googling for help, rather than reading man pages. And Google usually shows (or used to show) Stackoverflow posts, which usually contain a good answer.
So, half-serious suggestion: look for the most-viewed questions on Stackoverflow regarding the tool you're writing a man page for, and then put these questions and some good answers near the top of the man page?