Summary

Julia Evans explores what makes man pages effective and easier to navigate, drawing on examples from rsync, strace, curl, Perl, and the ASCII man page. She crowdsourced favorite man pages on Mastodon and catalogs specific techniques: options summaries, category-based organization, embedded cheat sheets, tables of contents with hyperlinks, per-option examples, and table formatting. She also touches on the GNU project's preference for info manuals over man pages and notes tools like tldr and Dash that supplement man pages. The post frames man page improvement as a design challenge within a constrained format.

Key Insight

Man pages can be dramatically improved through design techniques like options summaries, categorical organization, embedded examples, and cheat sheets — all within the existing constrained format.

Spicy Quotes (click to share)

• 3

  could the man page itself have an amazing cheat sheet in it? What might make a man page easier to use?

• 3

  once you're listing almost the entire alphabet, it's hard

• 3

  I can never remember the name of the -l grep option. It always takes me what feels like forever to find it in the man page

• 3

  I think adding a table of contents and adding internal hyperlinks is kind of a nice middle ground where we can make some improvements to the man page format without maintaining a totally different form of documentation.

• 5

  I've heard from some Emacs users that they like the Emacs info browser. I don't think I've ever talked to anyone who uses the standalone info tool.

• 3

  After a certain level of complexity a man page gets really hard to navigate

• 2

  Man pages are such a constrained format and it's fun to think about what you can do with such limited formatting options.

Tone

curious, exploratory, practical