|Keep It Simple, Stupid|
I wouldn't say perl is poorly documented, but that it, like many languages, relies heavily on some basic proficiency with the underlying OS and its rules.
What many Unix/Linux advocates seem to forget is that Windows has a different mindset, one that needs to be unlearned or discarded when dealing with *nix os's.
For example, I'm still pretty new to perl and had a project dropped in my lap. Write, in way too little time, a form-based emailer. Simple stuff for you folks, I'm sure, but since the lionshare of my development experience is with Windows languages, it wasn't something I felt entirely comfortable doing.
So I fired up several search engines, blundered around until I found some relevant material and managed to scrape something together. I did manage to meet the deadline, but I would never consider posting the code because it's flat out awful.
In finishing the project, I did run into several hurdles that would have been easier to solve had they been documented more clearly.
For example, you all know (I'm sure) that here documents are, by default, interpolated. Granted, it's not the best way to include a stylesheet, but I was against a time crunch. However, the stylesheet had external file references...
As another example, I didn't find clear examples of printing scalars with leading zeros or sending email attachments from mtulti-part forms until I heard about this site today. (If I'd only found the site a few months back...)
Each of these three behaviors took ~two days to puzzle out. I would have been far happier if I'd seen, very clearly in "Learning Perl," a warning about the interpolation issue. I did manage to figure it out using "Learning Perl" and "Programming with Perl," but it took a bit of page flipping.
You've all paid similar dues, I'm sure.
I have three main points:
Compared to other languages, perl is reasonably well documented. that's not to say there aren't areas where improvements could be made, but the docs are out there.(P.S. In general, _please_ design your pages so they can be easily printed. Far too many sites clip content when printed.)