Oh, pish posh, (i_recognize_you_name_omitted) ... we all know better.   Everyone reads the documentation first.   Then, they go out and write something with it.   If everyone just did that and said nothing, why, there would be no reason at all for PerlMonks to exist or for any of us to while away our time here, both reading and contributing as best we can.   But we do ... we all do ... and that is precisely why “petitioning the Monks” is, and remains, the most fruitful way to address a particular issue.

Documentation is tough to write, because it is usually written by the author herself.   She knows it too well.   She’s too close to it.   Quite often it is the secondary documentation, written by end-users who have read and absorbed the original perldocs, which is the most valuable in practice.   (And in the ideal world, that feedback loops back around to an improvement in those docs.)

I frankly don’t think that it is right to answer a post with, “RTFM,™” let alone to do so as an Anoymous Monk.   It is far better, and considerably less discourteous, simply to not to answer at all.   Let’s never “shut out” conversation, even those with which we do not agree.   Just let it perish on the vine in silence, if it may.   My very-legitimate and urgent need to seek the wise counsel of my peers on this matter, remains.   I mean no harm, and I mean to waste no one’s time.