Beefy Boxes and Bandwidth Generously Provided by pair Networks
We don't bite newbies here... much
 
PerlMonks  

RE: The sad state of Perl documentation

by footpad (Monsignor)
on Sep 20, 2000 at 00:53 UTC ( #33200=note: print w/ replies, xml ) Need Help??


in reply to The sad state of Perl documentation

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:

  1. If you write documentation, web articles, pod, or even answers to newsgroup/discussion messages, please take a moment to step back and review the technical overhead your information requires. I consider myself a literate, intelligent person, but half the man pages are too obscure for me. Yes, I can eventually puzzle them out, but I really don't have the time to invest. (I've got five projects due by the end of next month.) If you obfuscate behind a dizzying array of details, I get lost and annoy the heck out of my sysadmin..

    At the very least, provide some cross-references for those of us who aren't as experienced as you are. (Remember when "man printf(3)" caused you errors?)

  2. If you don't like the way one author has put it and you can't find one you like, then this is an opportunity for you to step up. For example, I am in the process of writing short web articles for a site I'm bringing online. Nothing that would appeal to you folks, I know, but it's stuff I ran into while learning the language, the rules, and the OS. You can do the same. There are several places where you can get free server space; use it.

  3. If you provide links, web articles, or other online content, please review those from time to time. Some folks haven't touched their pages since '96. 'Nuff said.</P

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.)


Comment on RE: The sad state of Perl documentation

Log In?
Username:
Password:

What's my password?
Create A New User
Node Status?
node history
Node Type: note [id://33200]
help
Chatterbox?
and the web crawler heard nothing...

How do I use this? | Other CB clients
Other Users?
Others exploiting the Monastery: (11)
As of 2014-07-30 19:59 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?

    My favorite superfluous repetitious redundant duplicative phrase is:









    Results (240 votes), past polls