February 20, 2026
Press F for / / /
Notes on Clarifying Man Pages
Turning cryptic help pages into cheat sheets — and the internet has feelings
TLDR: Julia Evans proposes man pages with clear summaries, categories, and examples to make command-line help less painful. Commenters split between loving short, example-first tools like tldr, demanding AI inside man pages, and blasting kubectl for sending readers online—proof that better, faster help matters to everyone.
Julia Evans floated a cozy revolution: make those intimidating command-line help pages (aka “man pages”) actually readable with summaries, categories, cheat sheets, and real examples. She shouted out the rsync man page for its tidy “OPTIONS SUMMARY,” noted how strace groups options by topic, loved Perl’s cheat sheet, and cheered examples—especially up front. The community? They brought receipts, memes, and a few torches.
One camp yelled “tldr or bust,” praising tldr.sh for short, example-first help you can run like “tldr grep.” Another crowd wants a smart assistant inside the terminal, with one commenter begging for an “AI CLI in the man page” to stop the endless “/ / /” scrolling for a single flag. Meanwhile, documentation purists resurfaced the old “Info vs man vs web” fight, citing GNU’s rule-of-thumb: program structure ≠ user-friendly docs. The biggest drama? kubectl’s man pages that punt you to online docs—cue the “I opened man to avoid the web!” outrage. Practical hackers tossed in tools like Mansnip for quick flag reminders (“what does curl -LO do again?”). It’s a spicy split: keep man pages minimal and example-rich, or go full AI-age concierge. Either way, nobody wants alphabet-soup help text anymore.
Key Points
- •Evans proposes making man pages more usable by incorporating cheat-sheet-like content directly within them.
- •The rsync man page demonstrates a concise SYNOPSIS paired with an OPTIONS SUMMARY listing one-line descriptions for each option.
- •The strace man page organizes options by functional categories rather than alphabetically to aid discoverability.
- •Perl’s perlcheat shows how embedded cheat sheets can present condensed, 80-column-friendly reference material.
- •Examples are highly valued; some man pages, including rsync and OpenBSD’s tail, place examples prominently, even at the beginning.