For anyone who regularly works with command-line tools, the man page is often the first—and sometimes only—source of documentation. Yet, while man pages are comprehensive, they can be notoriously difficult to navigate. After spending time improving the Git man pages last year and creating cheat sheets for tools like tcpdump, dig, and git, I began to wonder: What if the man page itself contained a superb cheat sheet? What changes could make these pages genuinely easier to use? Here are some early thoughts, inspired by examples from the community.

The Problem with Traditional Man Pages

Many man pages follow a familiar pattern: a dense, alphabetically sorted list of options under the SYNOPSIS or OPTIONS section. For example, the SYNOPSIS for ls looks like this: ls [-@ABCFGHILOPRSTUWabcdefghiklmnopqrstuvwxy1%,]. Similarly, grep starts with grep [-abcdDEFGHhIiJLlMmnOopqRSsUVvwXxZz]. When nearly the entire alphabet is listed, it becomes hard to quickly pinpoint the option you need. This is why many users abandon the man page and search for cheat sheets elsewhere.

Lessons from Exceptional Man Pages

I asked people on Mastodon for their favorite man pages, and several stood out for creative approaches to clarity.

The rsync Approach: OPTIONS SUMMARY

The rsync man page employs a solution I had not seen before: it keeps its SYNOPSIS extremely terse, like this:

Local: rsync [OPTION...] SRC... [DEST]

Then it introduces an OPTIONS SUMMARY section with a one-line description of each option:

• --verbose, -v — increase verbosity
• --info=FLAGS — fine-grained informational verbosity
• --debug=FLAGS — fine-grained debug verbosity
• --stderr=e|a|c — change stderr output mode (default: errors)
• --quiet, -q — suppress non-error messages
• --no-motd — suppress daemon-mode MOTD

Later, the standard OPTIONS section provides full descriptions. This arrangement gives you a quick overview without overwhelming you upfront.

The strace Method: Categorized Options

The strace man page organizes its options by category, such as General, Startup, Tracing, Filtering, and Output Format, instead of alphabetically. This grouping helps you jump directly to the relevant cluster of options. For users who know what kind of option they need (e.g., filtering), this is far more intuitive than scanning an alphabetical list.

A Collaborative Experiment: Reorganizing grep

Inspired by strace, I tried creating a categorized OPTIONS SUMMARY for the grep man page. For instance, options like -l (files with matches) often hide in the middle of the alphabet. I grouped them by function—output control, pattern matching, file selection—and added brief summaries. While the result was a fun exercise, I remain uncertain whether categories alone solve the problem. However, it sparked thinking about alternative structures that lower the time to find a specific option.

The Perl Innovation: Dedicated Cheat Sheet

Several people pointed me to the suite of Perl man pages (perlfunc, perlre, etc.). One standout is man perlcheat, which is essentially a printable cheat sheet embedded within the man page itself. It presents syntax in compact 80-character-wide blocks:

SYNTAX
foreach (LIST) { }     for (a;b;c) { }
while   (e) { }        until (e)   { }
if      (e) { } elsif (e) { } else { }
unless  (e) { } elsif (e) { } else { }
given   (e) { when (e) {} default { } }

This approach is remarkably effective. It provides a quick reference that fits in a terminal window, making it easier to learn and recall syntax without scrolling.

Envisioning a Better Man Page Structure

These examples suggest several principles for improving man pages:

1. Offer a top-level summary: Like rsync, include a concise option overview before diving into details.
2. Group by category: Instead of alphabetical order, cluster options by their purpose (e.g., “Output format”, “Filtering”) to help users find what they need faster.
3. Build in a cheat sheet: Dedicate a section—or even a separate page like perlcheat—to a condensed, printable reference.

Combining these ideas could produce a man page that serves both newcomers (who need an overview) and experienced users (who need quick recall). For example, a tool could have a SYNOPSIS with minimal options, a CHEAT SHEET with one-liners for common tasks, a OPTIONS SUMMARY with categorized brief entries, and a traditional OPTIONS section for full details.

Of course, this is just a starting point. Different tools have different documentation needs, and some man pages are already well structured. But the popularity of external cheat sheets suggests that many man pages are not meeting their users’ needs. By borrowing ideas from the examples above, we can make man pages more navigable and, ultimately, more useful.

I’m still early in thinking about this, but I hope these notes spark discussion. What other man pages have you found that break the mold? How might we standardize some of these improvements? Share your thoughts—and your favorite man pages.