One thing go's flag's package does that deserves a lot of blame is to automatically sort the flags alphabetically when looking at -help. And the fact that you need to hack your away around it instead of there being simply an option like nosort=true or whatever is even worse. The whole idea is crazy and basically equivalent to the statement that there order of parameters in -help serves no useful purpose.
And yet, I expect flags to be sorted in a man page; I rarely read things in a logical order, I'm just looking into what flag does what.
It's a convention-over-configuration thing I think. I mean they set a standard, so you can move on. The alternative is to sit and think and discuss about what order to put your documentation in.
You read text from top to bottom. Chances are that you're writing help text and describing the most commonly used flags at the top, and the more obscure ones lower down.
So you read the whole man page when you need a flag that does something specific or do you mean you never write new things and just have to look up flags already in use by some script?
Because for everything else that seems like a fascinating waste of time.
Because you don't always know which words the man page uses to describe specific functionality. So many ways to express similar ideas, language is fun that way.
