Julia Evans explores what makes man pages easier to use, drawing on examples from rsync, strace, curl, and others. Key ideas include adding an OPTIONS SUMMARY section with one-line descriptions, organizing options by category rather than alphabetically, embedding cheat sheets directly in man pages, adding tables of contents and internal hyperlinks to HTML versions, providing per-option examples, and using table formatting for scannable reference data. The post also touches on the GNU approach of preferring info manuals over man pages, and mentions adjacent tools like tldr.sh, fish shell's auto-completion generator, and the Dash docs browser.
Table of contents
an OPTIONS SUMMARYan OPTIONS section organized by categorya cheat sheeta table of contents, and links between sectionsexamples for every optionformatting data in a tablethe GNU approacha few more man-page-adjacent thingsit’s interesting to think about a constrained formatSort: