I came across the node: The sad state of Perl documentation (after reading Why can't mod_perl+Mason just work?). Since it was about 4 years old, I'd like to bring that topic up again. Some of the posts in that thread need updating, for example, the "perl documentation project" doesn't seem to be active anymore(am I right? google didn't return much)

In comparison with other recent programming languages, perl has the best set of books. I have a good collection of the O'Reilly set on my book shelf, the mere glancing of their standing there literally gives me warm feelings, I think it's probably physically healthy to posess those books:-) And no other language has a community as great as that of PM.

Recently, I've been looking into python. I'd say that although their books are of far less quality, their documentation/examples for the novice are superior. One example is the wxPython demo that shows how to build GUI with wxPython, it's written as an application (in wxPython), where the gui examples are listed in a tree node, and for each, one can click on "code", "demo" and "overview" tag to see the source, the result of running that code, and the documentation, respectively. Imagine we have such a demo tool for perl/Tk! Another example is the documentation that came with a standard installation of python, it is in one place, categorizes the modules according to their usage, searchable and indexed. Although ActivePerl came with a better presented documentation, it's still less thoughtful than that of python, and that of the perl books, IMHO.

Now the goal of this post is not to complain, so please spare me the flames. I meant to ask, is there something we, as a community, can/should do to ease the pain of the beginners, actually also those of us less talented veterans. I truely believe all documentation is already there, it's just their organization, or lack of, that makes it less helpful. This is sort of like the web before google.

In reply to Perl documentation by johnnywang

Title:
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, details, 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, summary, 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.