I'm sorry, that is completely useless advice. The manpages randomly bumble around in the abstraction level of their "explanations" and rarely use words that the average person would think of first to describe something.

I can't really reply to this; it just isn't true, and the text is right there for anyone to read if they want to see for themselves.

This is so "true" that there's even a realistic generator:

https://git-man-page-generator.lokaltog.net/

Ha! Best laugh I've had in a month!

sorry i'm gonna sound like i'm making an argument for authority but why do man pages have to appeal to the "average" person anyways? complex tasks require complex explanations to avoid weird hangups/errors.

every time i see people complain about the complexity of manpages i always wonder what their work looks like if manpages is the blocking issue to their understanding of a tool

I would agree that most manpages are pretty useful and that they don't necessarily need to be tutorials (it would be against Unix traditions, haha). Git's manpages and CLI are just a particularly bad word soup.

TODO: man page search engine with semantic term substitution (e.g. Bert). Possibly trained on stackoverfow.