well, i've had a few ideas ... but nothing particularly immediately applicable.

the strength i've seen with some of the PHP documentation is the ability to make associations between files/ modules. granted, it's just a special comment that's parsed, but it would be *very* helpful to be able to generate some of those programmatically.

the other 'weakness' i can see ... is somewhat related. for better or worse, perl uses the *nix mentality of building individual tools for individual jobs. the programmer is the one left to document the work (and rightfully so), *but* many of the dependencies, called and calling functions, etc get embedded in the developer's head, and don't always make it out into the doc.

while perldoc can be invaluable, for some it may be seen as and 'advanced topic'. i went looking for a 'cheat sheet' for POD commands a while back (when i asked a vaguely similar question) and was at a loss to find one. then i got sucked back into bug fixing, and never made the time to go back and find one.

In reply to Re: Reorganizing or fixing Perl's documentation? by geektron
in thread Reorganizing or fixing Perl's documentation? by BUU

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.