"I think that it is all too easy for those with long-term familiarity with the Perl docs to assume they are the very model of suffice and clarity, forgetting the struggles they themselves once had with them."
:-{)
Trust me! That's not me you're talking about, whether because of my own (relative) nooby-ness, my lack of a formal cs background; or simple simple-mindedness... but for my $.02, far too many perldocs -- esp. those for modules -- are on a par with the worst of the nixish documentation -- reflecting, IMO, a mindset by the writers that "I know what I mean; I worked hard to get here; let the reader share the pain."
Want a specific example of a core doc which doesn't begin to say enough to make use of its function? read truncate (which, unlike the POSIX doc for truncate(), fails to mention writability as a precondition); want one that's merely confusing or ambiguous? There's a wealth of such docs.
Fixed link to the truncate doc