[atoav]

I parsed (2) in the obvious way of: A manual should start with the common stuff 99% of people need and not with something obscure that you will only need once you are at the level that you know the tool you're using inside out.

That is like opening the manual for your dishwasher and reading a section about how you may check the control-boards conformal coating after the warranty has expired. Useful when you need it and have the repair skills, but a bad way to start a manual.

[skydhash]

That’s a tutorial or a getting started guide. The manual is a memory helper, like a tiny encyclopedia, not a teaching material.

[atoav]

How does that change my point about an order by frequency of use being superior? If it is a memory helper, then the stuff people tend to use more often is certainly the stuff that needs to be looked up more.

[skydhash]

That’s a variable order. I prefer a more consistent order like a default section structure (which a lot of man pages adopt) and an alphabetical order for flags (which a lot of man pages also adopt).

When I open a manual it’s usually for: flags and argument ordering; argument format (for things like string format or globbing). Some manuals are short enough that it can serve as a guide, but most assumes domain knowledge.

What you want is a cheatsheet. And there’s a lot on the internet and even some tools that collect them. But most practitioners write shell aliases and functions

[atoav]

I believe when people run one of my programs and read the manual, it is my job to not waste their time and respect why they chose to do that.

And that means the first screen they read should cover all the basics if possible.

[SSLy]

tutorial vs reference https://diataxis.fr/