HN
Today

Notes on Clarifying Man Pages

Julia Evans delves into the world of Unix man pages, exploring innovative ways to enhance their readability and utility for developers. She highlights examples like rsync's option summaries and curl's per-option examples, aiming to transform traditional documentation into more accessible resources. This practical, developer-centric analysis resonates on Hacker News for its focus on improving everyday command-line tooling.

5
Score
0
Comments
#16
Highest Rank
10h
on Front Page
First Seen
Feb 20, 11:00 AM
Last Seen
Feb 20, 8:00 PM
Rank Over Time
19162020202021262828

The Lowdown

The author, Julia Evans, shares insights gained from improving Git's man pages, questioning how to make these essential but often unwieldy documentation tools more user-friendly. Drawing on her experience creating cheat sheets for complex tools, she explores various techniques observed in exemplary man pages and related documentation systems, aiming to infuse them with more immediate, actionable information.

  • Concise Option Summaries: Some man pages, like rsync, provide a brief SYNOPSIS followed by a dedicated "OPTIONS SUMMARY" section offering single-line explanations for each option, improving scanability.
  • Categorized Options: Organizing options by functional categories (e.g., "General", "Tracing") instead of alphabetically, as seen in strace, can help users locate relevant commands more intuitively.
  • Integrated Cheat Sheets: The perlcheat man page demonstrates embedding condensed syntax cheat sheets, suggesting a broader application for quick reference within the man page format.
  • Prominent Examples: User feedback strongly favors man pages rich with examples. Some, like OpenBSD's tail or git-add, even place common usage examples near the beginning, while curl goes further by including an example for every single option.
  • Enhanced Navigation for HTML Versions: While not native to terminal man pages, HTML versions can be significantly improved with features like side-bar tables of contents and internal hyperlinks, as implemented for Git's documentation.
  • Data Presentation in Tables: The man ascii page effectively uses a table format to present data, making it highly scannable and suggesting opportunities for other man pages to adopt tabular layouts for structured information.
  • The GNU "Info" Approach: The GNU project often favors more extensive "info" manuals over man pages, which are generally more feature-rich (e.g., with examples) and accessible via dedicated tools or HTML, though this divergence can be a point of debate.
  • Complementary Tools: Various external tools and shell features, such as tldr.sh for quick examples, fish shell's auto-completion generation from man pages, and Dash's improved viewer, complement the traditional man page experience.

Ultimately, Evans ponders the potential within the constrained man page format to deliver more immediate value. Despite her own reluctance to read extensive documentation, she acknowledges the undeniable benefit of well-placed examples and seeks further community input on well-designed man pages.