4 ms·
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 fail
by Pewpewarrows 15y ago
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_ 15y agoIt 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 15y agoI'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 15y agoIn my experience, it's from some GNU folk who like their god-forsaken abomination that is info docs.
- Nick_C 15y agoman 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.