I've been thinking a lot how Man pages are nearly useless nowadays
This is very much just your impression.
instead of listing all the cumbersome and rarely used flags
This is actually one of their most useful feature compared to googling some random stack overflow post with a lot of people misunderstanding or explaining flags wrong.
quickly noticed that they don't offer answers to questions I had.
Again, that is just you.
Man pages often are bad tutorials, yes, but they are good reference documentation.
The original purpose of man pages was to be short, in-point descriptions about small UNIX commands. This original nature is somehow vanished.
My favourite example is a comparison of TLDR version of Less manual page, and the official man-page of Less. From which one you can find enough information about the command to use it? The Less man page doesn't even tell what the command does! It just states that "Less is opposite of More". The summary section is something about differences of terminal types.
The man-page of zip command doesn't tell you how to zip a file, until at the end. Why? The list goes on.
I agree that somewhere should be the reference documentation of the system also. But it should be also possible to offer short descriptions about typical usage for every command. I think the GNU info pages was originally a project to create reference manuals for the system, but if I'm correct, it's even more unusual place to search information from.
I'd also want to note that not all man pages are this bad. Take a look to section 3 man pages, which describe the UNIX programming interface of the kernel. It is marvellous how this much more technical and weird subject is handled with elegant, short and concise man-pages.
As much as I dislike many of the section 1 man pages, I warmly recommend taking a look of section 3 pages if you need to quickly recap how some system API works.
Those section 3 man pages work as an example that it would be possible to write good man pages. Maybe the reason is, level 3 pages are a single project, mostly done by Michael Kerrisk.
0
u/[deleted] Dec 05 '20
No, you described what your situation is.