Beefy Boxes and Bandwidth Generously Provided by pair Networks RobOMonk
P is for Practical
 
PerlMonks  

Comment on

( #3333=superdoc: print w/ replies, xml ) Need Help??
Opinion is divided on the question of a structure. XDG earlier in this thread commented that a structure was possibly unnecessary. I lean more towards your view. A structure, however loose, would provide guidance to reviewers and probably make potential reviewers more willing to comment without a) generating poor quality feedback, or b) putting people off reviewing because they don't want to send poor quality feedback.

Here's a few possible questions:

  • Does the synopsis clearly explain what the module does?
  • Is the syntax of the constructor and any main methods clear from the perldoc
  • Is there any functionality not documented (and therefore probably not present) you would like to see in the module
  • Is the perldoc correctly formatted (and if not, what is the problem and where)?
  • Does the meta data contain a) license, b) language used c) development stage?

As far as brainstorming goes, it might be worth considering opt-in/opt-out of perldoc reviews, setting up a site to post to rather than direct to the author etc. The danger there is that we then potentially start talking about review activity taking place somewhere other than CPAN, which I'm a little dubious about.

c.

Update: Then again, I just looked at recently active threads and found this

VGhpcyBtZXNzYWdlIGludGVudGlvbmFsbHkgcG9pbnRsZXNz

In reply to Re^2: Perldocs and peer reviews by g0n
in thread Perldocs and peer reviews by g0n

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!
  • 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
  • Outside of code tags, you may need to use entities for some characters:
            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?
    Username:
    Password:

    What's my password?
    Create A New User
    Chatterbox?
    and the web crawler heard nothing...

    How do I use this? | Other CB clients
    Other Users?
    Others browsing the Monastery: (7)
    As of 2014-04-19 06:20 GMT
    Sections?
    Information?
    Find Nodes?
    Leftovers?
      Voting Booth?

      April first is:







      Results (478 votes), past polls