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.
  • 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-putting and unfriendly to those coming to Perl from outside the culture of Unix, and without existing programming knowledge.

    Obviously, the Perl community has no particular obligation to address the documentation needs of that particular audience. But thanks to the success of the Web, and Perl's popularity among the self-styled "Web programmers" working their way up through the primordial ooze from HTML to Javascript to PHP to Perl, there exists a large-ish, and continually renewing, pool of Perl newbies who are coming to the language from that perspective, and who are looking for answers.

    Yes, it's always going to be more attractive to a certain subset of the more-knowledgeable types to make fun of these particular newbies, or to assert (either seriously or tongue-in-cheek) that they really don't deserve to learn Perl. But they're going to keep showing up anyway, and they're going to keep writing their crappy code and complaining, swinelike, about the fact that they can't make sense of the pearls represented by the existing documentation.

    So just write them some suitable documentation already. Not because you're in any way obligated to, but just so you can point them to it when they complain, rather than having to go through the much more tedious process of explaining to them why they're wrong to expect the community to provide that for them.

    Anyway, that's already happening. There is a lot more good newbie-oriented Perl documentation than there used to be. Which is great. But I still have that knee-jerk reaction of identifying with, and rising to the defense of, the people complaining about the documentation, when I see an item like this.

    But whatever.
    • 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.
      • Re:Same old story (Score:3, Interesting)

        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