Moreover, man pages serve as an essential resource that is much more reliably available than any other - when my network's routing packets in circles, the database server's on fire, and the duplicate has repeated the last transaction on every record, I don't care how "most users" don't use man pages or that web documentation is much more Google-able; I care that I have access to complete, detailed information (not the abbreviated version provided by --help) on all the utilities available to me; I care that apropos can help me recall the names of utilities I don't remember (something the article does not address); I care that I don't have to worry about having access to documentation, in addition to everything else, because it's all in a single, standardized, effective repository of man pages.
I really can't express strongly enough how much I disagree with the view that man pages are no longer relevant or necessary.
I myself also love reading man pages, but speaking of compatibility, I have to say that “--help” is a more universal way of showing help pages. Of course it’s better to have both of them though.
--help is fine, but almost never a substitute for a full man page, except for the most trivial of applications (unless your --help is as complete as a man page, in which case... good on you for providing full documentation, but I'll hate you a bit every time I unthinkingly drop two hundred lines of text in my terminal.)
I strongly suspect that --help is on the contrary less universal, given that there exist entire toolsets lacking the --help convention but having manual pages. There was almost a quarter of a century's worth of Unix tools that developed before --help was invented.
I never read man pages. If I need to check man, the tool failed in being user friendly. I'll then rather search online for what I need and blindly copy the first result on some stack exchange page..
If you can't immediately figure out how to properly set up and adjust a contractor's table saw, do you blame the table saw for being developed for professional contractors instead of newbies?
User friendlyness is a feature, and like all features it's not always worth adding to professional tools.
man pages are the first place I'm looking in for flags for commands I know for years, or when I'm using new commands — and it's always a frustrating experience when they don't exist.
Please, always ship man pages with whatever you write. It's /easy/ to do and has a great added value.
PS: doc on the web is so often irrelevant… either too old, or too recent — and in the rare cases where it's properly versioned, the workflow is something like “cmd --version ; google cmd $version” instead of just “man cmd”, which is nowhere as convenient or reliable.
Whether they're good or not, i feel manpages should ALWAYS be included every cli app. That being said, it is quite often that i begin my inquiry with manpages but then have to unfortunately look elsewhere for more info...specifically either a nice set of usage examples, or a bit more background on the "why" to use the cli app - in this order.
Nix commands show their man pages as their help, e.g. `nix-shell --help` is equivalent to `man nix-shell`. I think this works well, and reduces the burden of writing the same documentation over and over.
