# Notes on clarifying man pages

DevFeed: [Notes on clarifying man pages](<https://devfeed.tech/articles/notes-on-clarifying-man-pages-21125.md>)

Original publisher: [Read original article](<https://jvns.ca/blog/2026/02/18/man-pages/>)

Author: Julia Evans

Published: 2026-02-18T00:00:00Z

Content type: opinion

Language: en

Sources: [Julia Evans](<https://devfeed.tech/sources/julia-evans.md>)

Topics: [Documentation](<https://devfeed.tech/topics/documentation.md>), [Cheat sheet](<https://devfeed.tech/topics/cheatsheet.md>), [Tool](<https://devfeed.tech/topics/tool.md>), [ASCII](<https://devfeed.tech/topics/ascii.md>), [Git](<https://devfeed.tech/topics/git.md>), [ls](<https://devfeed.tech/topics/ls.md>), [Perl](<https://devfeed.tech/topics/perl.md>)

Tags: [ascii](<https://devfeed.tech/tags/ascii.md>), [cheat-sheet](<https://devfeed.tech/tags/cheat-sheet.md>), [documentation](<https://devfeed.tech/tags/documentation.md>), [examples](<https://devfeed.tech/tags/examples.md>), [git](<https://devfeed.tech/tags/git.md>), [notes](<https://devfeed.tech/tags/notes.md>)

## AI overview

The article explores ways to make Unix man pages easier to navigate and more useful. It considers embedding concise cheat sheets, using terse SYNOPSIS sections with OPTIONS SUMMARY sections, grouping options by category, providing condensed ASCII layouts, and including practical examples.

## Source excerpt

Hello! After spending some time working on the Git man pages last year, I've been thinking a little more about what makes a good man page. I've spent a lot of time writing cheat sheets for tools (tcpdump, git, dig, etc) which have a man page as their primary documentation. This is because I often find the man pages hard to navigate to get the information I want. Lately I've wondering - could the man page itself have an amazing cheat sheet in it? What might make a man page easier to use? I'm still very early in thinking about this but I wanted to write down some quick notes. I asked some people on Mastodon for their favourite man pages, and here are some examples of interesting things I saw on those man pages. an OPTIONS SUMMARY If you've read a lot of man pages you've probably seen something like this in the SYNOPSIS: once you're listing almost the entire alphabet, it's hard ls [-@ABCFGHILOPRSTUWabcdefghiklmnopqrstuvwxy1%,] grep [-abcdDEFGHhIiJLlMmnOopqRSsUVvwXxZz] The rsync man page has a solution I've never seen before: it keeps its SYNOPSIS very terse, like this: Local: rsync [OPTION...] SRC... [DEST] and then has an "OPTIONS SUMMARY" section with a 1-line summary of each option, like this: --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 Then later there's the usual OPTIONS section with a full description of each option. an OPTIONS section organized by category The strace man page organizes its options by category (like "General", "Startup", "Tracing", and "Filtering", "Output Format") instead of alphabetically. As an experiment I tried to take the grep man page and make an "OPTIONS SUMMARY" section grouped by category, you can see the results here. I'm not sure what I think of the results but it was a fun exercise. When I was writing that I was thinking