[cyphar]

> do you think that man pages are more important than web or in-cli docs?

Yes.

* Web docs are a problem because I don't always have access to the internet when trying to do something on my computer, and usually there are so many kinds of web doc generators that you have to figure out how the information you want is laid out. Web docs are useful as a quick-start guide or a very lengthy reference guide -- but not for the common usecase of "is there a flag to do X?"

* In-CLI docs are a cheaper version of man pages. In most cases, the output is larger than the current terminal size so you end up piping to a pager (where you can search as well), and now you have a more terse version of a man page. Why not just have a man page?

Man pages are useful because they have a standard format and layout, provide both short and long-form information, and are universally understood by almost anyone who has used a Linux machine in the past. "foo --help" requires the program to know what that means (I once managed to bootloop a router by doing "some_mgmt_cmt --help" and it didn't support "--help" -- I always use man pages now). One of the first things I teach students I tutor (when they're learning how to use Linux) is how to read man pages. Because they are the most useful form of information on Linux, and it's quite sad that so many new tools decide that they aren't worth the effort -- because you're now causing a previously unified source of information (man pages) to be fractured for no obvious gain.

I still add support for "--help" for my projects (because it is handy, I will admit) but I always include manpages for those projects as well so that users can actually get proper explanations of what the program does.

> I'm genuinely curious as I've never had anyone request man pages in our CLI.

Honestly, I would consider not using a project if an alternative had man pages (though in this case it would be somewhat more out of principle -- and I would submit a bug report to bring it to the maintainers' attention).

[majewsky]

> I still add support for "--help" for my projects (because it is handy, I will admit)

Some applications (e.g. Git) make "--help" redirect to man. What do you think of that?

[falcolas]

Personally, I still pull up "man git-pull" or similar. I'm actively annoyed that I have to remember that the AWS CLI is different in this regard.

Not to mention that using "--help" for man pages requires I open up a separate window when I typically just want a quick reference to the most used flags.

Moving man pages to a different command is like coming up with an alternative icon to the hamburger menu for your regular UI. Sure, all the functionality is still there, but it requires a full stop and search to remember where to find it.