Beefy Boxes and Bandwidth Generously Provided by pair Networks
No such thing as a small change

Comment on

( #3333=superdoc: print w/replies, xml ) Need Help??

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

In reply to RE: The sad state of Perl documentation by footpad
in thread The sad state of Perl documentation by SuperCruncher

Use:  <p> text here (a paragraph) </p>
and:  <code> code here </code>
to format your post; it's "PerlMonks-approved HTML":

  • Posts are HTML formatted. Put <p> </p> tags around your paragraphs. Put <code> </code> tags around your code and data!
  • Titles consisting of a single word are discouraged, and in most cases are disallowed outright.
  • Read Where should I post X? if you're not absolutely sure you're posting in the right place.
  • Please read these before you post! —
  • Posts may use any of the Perl Monks Approved HTML tags:
    a, abbr, b, big, blockquote, br, caption, center, col, colgroup, dd, del, div, dl, dt, em, font, h1, h2, h3, h4, h5, h6, hr, i, ins, li, ol, p, pre, readmore, small, span, spoiler, strike, strong, sub, sup, table, tbody, td, tfoot, th, thead, tr, tt, u, ul, wbr
  • You may need to use entities for some characters, as follows. (Exception: Within code tags, you can put the characters literally.)
            For:     Use:
    & &amp;
    < &lt;
    > &gt;
    [ &#91;
    ] &#93;
  • Link using PerlMonks shortcuts! What shortcuts can I use for linking?
  • See Writeup Formatting Tips and other pages linked from there for more info.
  • Log In?

    What's my password?
    Create A New User
    and all is quiet...

    How do I use this? | Other CB clients
    Other Users?
    Others musing on the Monastery: (6)
    As of 2018-03-19 00:10 GMT
    Find Nodes?
      Voting Booth?
      When I think of a mole I think of:

      Results (231 votes). Check out past polls.