Products · Pattern or everyday thing
Man pages
Raised as a usability problem by 80 people on Hacker News over 16 years (2011–2026), in 74 threads.
No issue was raised by at least 3 people in 3 threads this year.
No issue was raised by at least 3 people in 3 threads in the last 5 years.
Every issue, all time, most people first
Man page search returns unhelpful results for what users seekUnreviewed
20112026- Searching man pages requires digging around with apropos to find the right page2023-12-22
- Searching man -K for a phrase returns no useful hit, forcing scanning through dozens of results2021-04-09
- Can't find what they're searching for; man -K search returns unhelpful results2017-05-22
Options aren't alphabetical or grouped, so search means scrolling past matchesUnreviewed
20112026- Hard to find the needed option among dozens of entries2024-06-13
- Can't jump to an option's entry or find related references reliably in man pages2017-11-26
- Options aren't alphabetical or grouped, so finding one means searching past many unrelated matches2014-01-25
Searching for a specific flag matches many similar flagsUnreviewed
20112026- Finding a specific flag is hard because searches match many similar flags2021-09-01
- Users must scan dozens of irrelevant flags to find the right one2021-04-09
- Searching for a flag like -f matches unrelated flags and examples, burying the actual entry2020-12-05
Unreviewed issues were grouped by machine: Claude Haiku labelled each comment as a usability complaint, named what it's about and summed up the problem in a line, and a small model grouped similar problems. Nobody has checked them by hand. Expect mistakes.
The newest 50 complaints
- Man pages are a long list of options, useless for learning how to use a command2026-03-16
- Man pages are an endless unreadable list of options for newcomers2026-03-12
- Searching for ~ or dash fails because man renders them as lookalike characters2026-03-11
- Can't remember which man section number holds which command2026-02-20
- Searching for a flag fails when it isn't the first non-whitespace text on a line2026-02-20
- Man pages assume a particular audience and have inconsistent command line flags2026-02-20
- Hours wasted searching for flags, then scrolling up to confirm the right sub-command section2026-02-20
- Filtering with & can hide sub-commands when many matches appear2026-02-20
- Man pages are dense and assume implicit knowledge, so most users can't follow them2026-02-15
- Man pages are lengthy, so finding usage examples means scrolling or searching the web instead2026-01-18
- Common, useful flags are buried deep in documentation, behind obscure details2025-12-22
- Man page viewer needs memorized keypresses, and dense wall-of-text pages are hard to scan2025-09-16
- Can't jump straight to a specific option like -ss when looking up parameters2025-04-09
- Can't jump straight to a flag's description, must use regex hacks2025-04-09
- Terminal man viewer is an unfamiliar interface compared with web docs2025-04-09
- Hundreds of options with inconsistent, arcane, unintuitive syntax are hard to sift through2025-04-09
- Man pages are far longer than needed for simple usage questions2025-02-09
- Table shows two characters per line, which is confusing to read2024-07-23
- Hard to find the needed option among dozens of entries2024-06-13
- Searching man pages requires digging around with apropos to find the right page2023-12-22
- Useful sections like EXAMPLES are buried at the end, forcing users to scan dense text2023-12-14
- Navigating long man pages is clumsy and finding things in them takes work2023-11-04
- Can never find command-line options when searching for them2023-10-15
- Hard to find command line arguments; relies on primitive text search instead of navigable links2023-10-15
- Overwhelmed by endless configuration options and command line flags2023-10-06
- Man pages list options but don't explain what the program actually does2023-05-25
- Man pages are too terse and dense for beginners to learn from2023-05-24
- The standard man page format is extremely confusing even after a decade of use2023-03-17
- Long man pages are an all-or-nothing scroll, so you can't easily skip to sections2022-10-02
- Large man pages can't be navigated; finding things means plain text search with no way to tell hits apart2022-08-19
- Man pages are over the top and a chore to digest, stalling common usage2022-04-30
- Too heavyweight; crawling dozens of pages to find a few common options2022-04-12
- Obscure joke in documentation is confusing to readers who lack the reference2022-03-21
- Hard to learn a topic without already knowing the exact function or header names2022-02-17
- Finding a specific flag is hard because searches match many similar flags2021-09-01
- Examples are buried deep in man pages, so users can't find usable how-to guidance2021-07-01
- Searching man -K for a phrase returns no useful hit, forcing scanning through dozens of results2021-04-09
- Users must scan dozens of irrelevant flags to find the right one2021-04-09
- Man pages are so dense and obtuse that beginners can't learn from them2021-03-22
- Searching for a flag like -f matches unrelated flags and examples, burying the actual entry2020-12-05
- Man page is poor, with few reliable reference clients to learn from2020-10-23
- Hard to find which command or option performs a given task2020-05-27
- Hard to find which man pages exist or what they are called2020-05-03
- Skimming exhaustive man pages to find a forgotten trivial command is infuriating2020-02-26
- Examples are buried at the end after exhaustive flag documentation, making them hard to reach2020-01-23
- Search is nearly unusable unless the exact term is already known2020-01-05
- Man command output is useless, and the commands are hard to find via search2019-10-17
- Massive wall of text makes it hard to find the few options needed mid-task2019-09-21
- Man pages are hard to use for common tasks, so people search the web instead2019-07-09
- Man pages too short to solve problems; finding answers means grepping several pages2019-06-23