One thing that always infuriates me: If I go to --help or the man page for your command, and don't see a real example of how to use it immediately, you've failed me as a user. Seeing your syntax tree and a list of every option and its description doesn't help me when I'm first trying to use your program. I just want to see one or two quick examples of real commands with a short sentence explaining each. After that I'…
I've seen a few discussions of this around. I agree with you, but there are some who believe that examples do not belong in manages (not sure what their rationale is).
In my experience, it's from some GNU folk who like their god-forsaken abomination that is info docs.