"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