Some man pages include examples, which I always greatly appreciate.

Ha ha ha, no you are most certainly not alone, that’s gotta be one of the most common gripes with new users. Those things were written in the 70s and have remained unchanged since. It’s a standardization thing. :)

I find --help to be often useful, but man is hard to sell. As a tool to know more details of an option or to know everything that’s available, it’s great. As a first contact with the CLI tool or a quick lookup, man past the first paragraph is often a waste of time. For most lookups cheat.sh is much quicker.

Though I’ve recently been using clipea with GPT-4, and it’s by far the best experience. Fastest way to have straightforward one-liners that do pretty much what you asked for.

That’s because you’re a woman.

*runs for cover*

man is self-paging and searchable. It uses some old-school emacs bindings like Ctrl + V from before PgDn was a standard key. So I’m not claiming it’s intuitive.

If cmd --help spews a bunch of info to the screen, you basically have to handle it with grep or less or go modern.