Stories
Slash Boxes
Comments
NOTE: use Perl; is on undef hiatus. You can read content, but you can't post it. More info will be forthcoming forthcomingly.

All the Perl that's Practical to Extract and Report

The Fine Print: The following comments are owned by whoever posted them. We are not responsible for them in any way.
 Full
 Abbreviated
 Hidden
More | Login | Reply
Loading... please wait.
  • Same old story (Score:2, Insightful)

    Granted, that the people delivering this message frequently beg to be ignored (or worse) by virtue of their newbiehood-cum-attitude. But this particular criticism has been aimed at the Perl community for a long time (at least as long as I've been paying attention, including when I was the one with the newbiehood-cum-attitude).
    Each side is technically "right," at least within its own frame of reference. Yes, Perl's available documentation has been, and still is (though to a lesser extent than previously) off
    • This is not about whether or not the docs need improvement. The docs can always use improvement. This is about the way some people try to go about it: with a very low signal-to-noise ratio.
      • Well, right. I realize that's what you were commenting on, and your point is, of course, perfectly valid. But again, this is just the latest in a very long series of such incidents, and at some point it's probably worth taking a step back and asking if there might be a larger lesson to be learned.

        I think there is such a larger lesson: that the newbies who persist in voicing this particular frustration have a point. Their needs really aren't being adequately met by the existing docs. Pointing out that they could be asking for help in a more appropriate manner misses the point somewhat. The fact that they exhibit an annoyingly low signal-to-noise ratio is not just some side issue; it is itself a symptom of their newbiehood. It doesn't make sense to me to complain about the symptom while ignoring the underlying disease.

        It's not just that the docs need improving. It's that this particular shortcoming in the docs grows from a particular mindset, a mindset that needs to be transcended in order for the shortcoming to be effectively addressed.

        That mindset basically goes like this: The documentation is perfectly adequate (stunningly good, actually) for people like me. You people complaining that you don't understand the docs are in fact just broken. Once you fix yourselves (that is, once you make yourselves more like me), you, too, will find the docs adequate. Fixing your newbiehood is not my problem. So go away, you silly newbies, before I taunt you another time.

        Phrased this way, I think it's pretty clear that this attitude runs counter to some of the deeper philosophical underpinnings of Perl. And that disconnection is a problem, because Perl, with its humble, do-what-you-mean, making-easy-things-easy attitude, is like catnip to these newbies. They will continue to be attracted to it in large numbers because darn it, it just keeps getting their jobs done. So, if you've got a language that serves as this big newbie honeypot, then at some point you might want to get around to providing some documentation specifically tailored to those newbies' needs.

        Please note: You're not obligated to provide it. But if you choose not to, you're going to continue to experience these annoyingly-low-signal-to-noise-ratio complaints. And at some point, I'd like to think that a little laziness, impatience, and hubris would kick in, and you'd just say, oh, to hell with it. Here's your documentation, newbies. Go read it, and stop bothering me already.