The assumption that "xxxxx() works the same way as xxxx() (2)" will mean something is rife in some parts of the docs.
I do not see a problem with that. It's just a reference. Not also that in many cases, it cannot be documented more accurately in the Perl docs, as it will indeed use the xxxx() from your system, and that may be implemented differently on different platforms.
And there are other parts that still go right over my head. Eg. The use of \G (and (?>...) for that matter ) in regexes. If I sit and read the docs and play in my REPL, I can usually, eventually make these constructs deliberately do something of my choosing. Usually. But you'll rarely if ever see me use them to solve real problems. I've simply never found the analogy or example that allows me to assimilate them into my way of thinking.
Sure, but what's the alternative? Write even more documentation? That will make the fraction that's saying there is too much documentation making it hard to find stuff stronger. Or would could just take out a lot of things from Perl (regexes are hard -- remove them. IO is hard -- remove them), moving them into libraries (or modules). But then, if I want C, I know where to get it.
Concluding that an OPs failure to understand the relevant part of the docs is due to a lack of "due diligence", is assumptive in the extreme.
Perhaps. I don't see many questions of the form of "I read 'X Y Z' in the documentation. Can anyone explain what it means, and whether (and how) I can use it to solve problem W'?". If there are parts of the documentation that turn out to be unclear for large groups of people, I'd like those people to be vocal about. If they don't give any indication they've checked the documentation, and they ask a question that can be answered by just quoting from the documentation, I'll assume they haven't checked the documentation.