[Pewpewarrows]

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'll dive into the mess that is the dozens of flags and inputs to decipher exactly what I want.

[pmr_]

It always struck me as odd that man pages tend to have the EXAMPLES section as the last section of the document. I really would like it the other way around but this kinda fits with a bottom-up approach to learning. Look at the small details then get the full picture and how it's supposed to be used.

[code_duck]

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

[Nick_C]

In my experience, it's from some GNU folk who like their god-forsaken abomination that is info docs.

[Nick_C]

man docs have a specific format, a followed by b followed by c, etc. Examples are towards the end, near bugs and author.

It may not be how you want it, but at least it's consistent. shift-G will take you straight to the end, with hopefully some examples.