Notes on clarifying man pages

Developers are redesigning man pages

Technical writers and developers are overhauling the traditional Unix man page to include integrated cheat sheets and condensed summaries. This movement aims to fix the navigation issues inherent in decades-old documentation for tools like git, tcpdump, and dig. Many users find standard man pages difficult to scan, leading them to rely on third-party websites instead of local terminal files. Modern projects are now experimenting with new structures to prioritize speed and usability. These changes focus on reducing the "alphabet soup" of command-line flags and placing relevant examples at the top of the file. Writers are also leveraging HTML versions of these documents to add features like sidebars and internal hyperlinks.

Fixing the alphabet soup problem

Standard man pages often list every available option in a single, unreadable block. The ls command, for example, displays nearly the entire alphabet in its synopsis, which provides little value to a user in a hurry. Documentation for grep follows a similar pattern, forcing users to scroll through dozens of flags to find a single specific function. The rsync utility offers a cleaner alternative by keeping its synopsis extremely terse. It uses a Local: rsync [OPTION...] SRC... [DEST] format that tells the user the basic structure without the clutter. rsync then provides an OPTIONS SUMMARY section that gives each flag a single-line description before the long-form documentation begins.

• rsync uses a terse synopsis to improve readability.
• An OPTIONS SUMMARY provides one-line descriptions for every flag.
• Full descriptions remain in a separate, detailed section later in the document.

Organizing commands by logical category

Alphabetical lists often hide the most important functions of a tool. The strace man page solves this by grouping options into categories like General, Startup, Tracing, and Filtering. This structure allows a developer to find all output-related flags in one place rather than hunting through an A-to-Z list. Experimental versions of the grep man page are testing similar categorical layouts. Users often struggle to remember specific flags, such as the -l option for listing filenames. Grouping this under a "Output Control" heading makes it significantly easier to locate than searching through the entire manual. Categorization turns a reference document into a functional tool for discovery.

Using ASCII tables for fast scanning

The man ascii page remains a favorite among developers because it uses a strict table format. It displays Octal, Decimal, Hex, and Character values in aligned columns that are easy to scan. This layout proves that even within the 80-character constraints of a terminal, visual structure can replace dense paragraphs. The Perl documentation suite takes this further with man perlcheat. This page functions as a dedicated ASCII cheat sheet rather than a traditional manual. It uses condensed blocks to show syntax for loops, conditionals, and variable types.

• perlcheat provides 80-character wide syntax blocks.
• The man ascii page uses a table format for instant data retrieval.
• Tables reduce the cognitive load required to find specific character codes or syntax rules.

Prioritizing examples over technical specs

Most users search man pages specifically for usage examples, yet these sections often appear at the very bottom of the file. The OpenBSD version of the tail command moves these to the end but keeps them focused on the two most common use cases. Some developers are now moving these examples to the very beginning of the document to save users from unnecessary scrolling. The curl project provides a gold standard for example-driven documentation. Every single option in the curl manual includes a corresponding example. For instance, the entry for --cert explicitly shows how to use it alongside the --key flag. This helps users understand the dependencies between different options without reading the entire manual.

Modernizing documentation with AsciiDoc

The Git project is currently using AsciiDoc to generate its documentation, which allows for a more flexible HTML output. Developers recently added a table of contents to the sidebar of the web-hosted Git man pages. This sidebar stays visible as the user scrolls, providing a map of the document that the terminal version lacks. Internal hyperlinks are the next major goal for the Git documentation team. These links allow users to click on phrases like INCOMPATIBLE OPTIONS and jump directly to the relevant technical warnings. Using a toolchain like AsciiDoc makes these improvements possible without forcing writers to maintain two separate versions of the same manual.

• Git uses AsciiDoc to generate both terminal and web documentation.
• HTML versions now feature a persistent table of contents in the sidebar.
• Internal hyperlinks allow for instant navigation between conflicting command options.

The split between GNU and OpenBSD styles

A long-standing divide exists between GNU coreutils and OpenBSD documentation philosophies. GNU man pages for tools like tail are often brief because the project prefers the Info format for detailed manuals. However, many modern developers find Info files difficult to use and rarely open them. OpenBSD man pages generally include more practical examples within the man page itself. For complex tools like Bash or the GNU C Library, many developers now skip the terminal entirely in favor of HTML reference manuals. The transition toward HTML allows for better formatting, but the terminal man page remains the primary "offline" resource for most engineers.

Building better documentation tools

Several new tools are emerging to help developers create and view better documentation. Mandoc serves as a suite of tools for compiling man pages, while Pandoc allows for easy conversion between Markdown and the traditional man format. These tools make it easier for developers to write documentation in modern languages while still supporting the legacy terminal format. The tldr-pages project has also gained significant traction by providing simplified, community-driven man pages. While these are not official manuals, they follow the "cheat sheet" philosophy by offering only the most common examples. The success of tldr suggests that the traditional man page must evolve to stay relevant in a modern development environment. Editorial Note: Writers should continue to experiment with these formats to see which layouts actually improve the developer experience.