The worst is where you assume a vanilla implementation of some basic functionality, so you skip the explanation, but actually, there's a quirk inside that you only discover after scratching your head for a while.

Newbies are lucky in this way, that they don't have even a mistaken reason to skip reading the basics.

Unix/ Linux man pages are really hard to understand because of this

True, but they make up for it by being also very difficult to use in their intended role as aides-memoire, both because of the way they're written and because the relatively primitive format provides no aid to search or navigation.

I find `man X | grep Y` actually works OK, and the "see also" at the bottom is quite helpful for finding related information.

But if I don't already know exactly what I'm looking for, it's hard to use. It's really difficult to "learn about" how to open sockets if I can't remember sockaddr_t exact spelling or the right header to include.

On a BSD, try ‘man -Otag=l ls’ or ‘:tl’ (from less) for e.g. ls -l. This also works for larger man pages: ‘man -Otag=OCRNL termios’. More specifically, this requires the mandoc man implementation, which is also available on Linux — it’s what I prefer for all my machines.

tl;dr: it’s groff(1), not the -man and -mdoc formats, which is primitive (in this sense).