The problem with linux is that nobody owns responsibility for making the whole man system good.
Linux kernel stuff is covered by the linux man project. This is run by Kerrisk, who is a good communicator - _The Linux Programming Interface_ reads like Stevens but is richer in practical advice.
But if you go to the man page for something like awk or bash or grep (the common use-case - where you need a quick reference), they're maintained by the team who write the tool, or - often enough - not maintained by the team. There are undocumented flags, often the doc only tends to make sense if you already understand the internals of the tool. GNU tool man pages are generally obtuse.
BSD and plan 9 have much better man systems. Unless a linux distribution comes along and makes a conscious effort to solve GNU/linux doc, the man system available to linux users will always suck - it's structural.
"But if you go to the man page for something like awk or bash or grep [...]"
And this is where you are doing it wrong. For GNU tools, the man page is just a stub. The official documentation is maintained in the form of "info" pages.
Now, you may consider this obtuse (I sure do), but it doesn't mean there is no documentation.
Linux kernel stuff is covered by the linux man project. This is run by Kerrisk, who is a good communicator - _The Linux Programming Interface_ reads like Stevens but is richer in practical advice.
But if you go to the man page for something like awk or bash or grep (the common use-case - where you need a quick reference), they're maintained by the team who write the tool, or - often enough - not maintained by the team. There are undocumented flags, often the doc only tends to make sense if you already understand the internals of the tool. GNU tool man pages are generally obtuse.
BSD and plan 9 have much better man systems. Unless a linux distribution comes along and makes a conscious effort to solve GNU/linux doc, the man system available to linux users will always suck - it's structural.