2 ms·

Less than one time in my life (one time exactly but not really) has a man page helped me to figure out how to use a command. To me it seems man pages are writte

Less than one time in my life (one time exactly but not really) has a man page helped me to figure out how to use a command. To me it seems man pages are written for extraterrestrial beings, hard to understand, only featuring some examples (which don't cover even the very basic use cases anyway) hidden among pages deep down below. The first thing I find when I google a command are examples, usually covering exactly what I need. So I believe the entire man pages system is a crime against humanity or a piece of obscure art like the Voynich manuscript at best.

akkartik 5y ago
God knows man pages aren't perfect. But they're what all the extraterrestrial beings around you are reading to create the docs with examples that suit you better when you perform searches on the internet.
tannhaeuser 5y ago
It's encouraged for manpages to have an EXAMPLES section, though I feel you. I think a big problem is that command line options have gone ad absurdum with hundreds of options decades ago already (prompting GNU-style long options) and the more recent trend towards "subcommands" as in git, docker, etc.
dr_hooo 5y ago
I recently discovered and am enjoying [0] for the cli, and [1] for decoding shell fragments encountered in scripts [0] https://tldr.sh/ https://tldr.sh/ [1] https://explainshell.com/ https://explainshell.com/
- qwerty456127 5y ago
  Yes, tldr is an awesome and I used it for some time but its library wasn't rich enough. Perhaps it got bigger nowadays, maybe I'm going to revisit it.
sleepydog 5y ago
> The first thing I find when I google a command are examples, usually covering exactly what I need. I see a lot of people reflexively reaching for Google or Stackoverflow when working with a command (or even a programming language) that they aren't familiar with. Often it will get the job done, but I feel it only provides a shallow understanding of what the tools can do. Do you similarly search for examples when trying to use an API in your language of choice, or do you consult the reference documentation? Take, for example, fio(1), a tool for running I/O benchmarks. It probably has over 100 options. It is insanely flexible. You might not even consider using it if you didn't know what it was capable of. You can either sift through dozens of mailing list conversations and stackoverflow threads to find the perfect benchmark, or you can browse the man page that explains all the options. I guess what I'm saying is that one is not a replacement for another. If you're skipping the man page, you're losing something. Whether or not you'll miss it is another question.

akkartik 5y ago

God knows man pages aren't perfect. But they're what all the extraterrestrial beings around you are reading to create the docs with examples that suit you better when you perform searches on the internet.

tannhaeuser 5y ago

It's encouraged for manpages to have an EXAMPLES section, though I feel you. I think a big problem is that command line options have gone ad absurdum with hundreds of options decades ago already (prompting GNU-style long options) and the more recent trend towards "subcommands" as in git, docker, etc.

dr_hooo 5y ago

I recently discovered and am enjoying [0] for the cli, and [1] for decoding shell fragments encountered in scripts [0] https://tldr.sh/ https://tldr.sh/ [1] https://explainshell.com/ https://explainshell.com/

qwerty456127 5y ago
Yes, tldr is an awesome and I used it for some time but its library wasn't rich enough. Perhaps it got bigger nowadays, maybe I'm going to revisit it.

sleepydog 5y ago

> The first thing I find when I google a command are examples, usually covering exactly what I need. I see a lot of people reflexively reaching for Google or Stackoverflow when working with a command (or even a programming language) that they aren't familiar with. Often it will get the job done, but I feel it only provides a shallow understanding of what the tools can do. Do you similarly search for examples when trying to use an API in your language of choice, or do you consult the reference documentation? Take, for example, fio(1), a tool for running I/O benchmarks. It probably has over 100 options. It is insanely flexible. You might not even consider using it if you didn't know what it was capable of. You can either sift through dozens of mailing list conversations and stackoverflow threads to find the perfect benchmark, or you can browse the man page that explains all the options. I guess what I'm saying is that one is not a replacement for another. If you're skipping the man page, you're losing something. Whether or not you'll miss it is another question.