Why Unix Man Page Sucks

Unix Man Page

unix man page starts with this type of obscurantism:

SYNOPSIS
  gzip [ -acdfhlLnNrtvV19 ] [-S suffix] [ name ...  ]
  gunzip [ -acfhlLnNrtvV ] [-S suffix] [ name ...  ]
  zcat [ -fhLV ] [ name ...  ]

Here, the mindset of unix idiots, is that somehow this “synopsis” preamble is technically precise and superior. They are thinking that it captures the full range of syntax in the most concise way.

In practice, nobody reads it. It's actually not accurate as one'd thought. It is machine unreadable and human incomprehensible. Worse of all, the semantic of unix software's options are the worst rape to any possible science in computer science.

Learn Technical Writing from Unix Man in 10 Minutes

2011-01-03 Quote from man apt-get

remove

remove is identical to install except that packages are removed instead of installed.

Translation:

kicking

kicking is identical to kissing except that receiver is kicked instead of kissed.

unix man page improved, tldr page

“tldr page” tried to improved unix man page by rewriting it starting with most used examples. This project begin in 2013.

after 30 years, people finally admitted that unix man page sucks.

• https://github.com/tldr-pages/tldr