6 ms·

Unless you already know your users will want man pages, I wouldn’t bother also outputting them as they just aren’t used often enough anymore. I don't know wher

Unless you already know your users will want man pages, I wouldn’t bother also outputting them as they just aren’t used often enough anymore. I don't know where this is coming from, me and my colleagues are reading man pages every day. I would be interested how much others read them.

kolme 8y ago
I strongly disagree on this one too. That's the first place I look for help and it annoys me to no end when a CLI program that doesn't come with one. I stopped taking seriously the article at that point and quickly skimmed through the rest of it. Man pages are a great unix culture heritage, please new developers don't give up on them!
- davidhcefx 8y ago
  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.
  - larkeith 8y ago
    --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.)
    - smarinov 8y ago
      Unless it just opens the man page if it is so long. Like git.
  - JdeBP 8y ago
    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. * https://unix.stackexchange.com/a/416796/5132 https://unix.stackexchange.com/a/416796/5132 * https://unix.stackexchange.com/questions/207136/ https://unix.stackexchange.com/questions/207136/
    - dickeytk 8y ago
      How can you say it's less universal when it doesn't work on windows?
- larkeith 8y ago
  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.
Arkanosis 8y ago
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.
wingerlang 8y ago
As you're getting mostly replies agreeing - I never read man pages. I look up the odd parameter every now and then though.
- purerandomness 8y ago
  Do you mean you look up parameters somewhere else, e.g. in a web browser using google?
  - wingerlang 8y ago
    Pretty much, yes.
deadbunny 8y ago
> I don't know where this is coming from From people who don't know how to use man pages.
- voltagex_ 8y ago
  BSD manpages or Linux manpages? There are very few Linux manpages that I'd consider acceptable.
thrower123 8y ago
When man pages are good, they're good. When they are bad, they are super verbose, incomprehensible, sparse, or otherwise completely useless.
maaaats 8y ago
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..
- falcolas 8y ago
  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.
chriswarbo 8y ago
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.
mxuribe 8y ago
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.

kolme 8y ago

I strongly disagree on this one too. That's the first place I look for help and it annoys me to no end when a CLI program that doesn't come with one. I stopped taking seriously the article at that point and quickly skimmed through the rest of it. Man pages are a great unix culture heritage, please new developers don't give up on them!

davidhcefx 8y ago
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.
- larkeith 8y ago
  --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.)
  - smarinov 8y ago
    Unless it just opens the man page if it is so long. Like git.
- JdeBP 8y ago
  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. * https://unix.stackexchange.com/a/416796/5132 https://unix.stackexchange.com/a/416796/5132 * https://unix.stackexchange.com/questions/207136/ https://unix.stackexchange.com/questions/207136/
  - dickeytk 8y ago
    How can you say it's less universal when it doesn't work on windows?
larkeith 8y ago
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.

Arkanosis 8y ago

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.

wingerlang 8y ago

As you're getting mostly replies agreeing - I never read man pages. I look up the odd parameter every now and then though.

purerandomness 8y ago
Do you mean you look up parameters somewhere else, e.g. in a web browser using google?
- wingerlang 8y ago
  Pretty much, yes.

deadbunny 8y ago

> I don't know where this is coming from From people who don't know how to use man pages.

voltagex_ 8y ago
BSD manpages or Linux manpages? There are very few Linux manpages that I'd consider acceptable.

thrower123 8y ago

When man pages are good, they're good. When they are bad, they are super verbose, incomprehensible, sparse, or otherwise completely useless.

maaaats 8y ago

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..

falcolas 8y ago
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.

chriswarbo 8y ago

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.

mxuribe 8y ago

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.