Beefy Boxes and Bandwidth Generously Provided by pair Networks
Your skill will accomplish
what the force of many cannot

Re: Perldocs and peer reviews

by theorbtwo (Prior)
on Jan 31, 2005 at 13:58 UTC ( #426589=note: print w/replies, xml ) Need Help??

in reply to Perldocs and peer reviews

The problem with that is that it's possible for the docs to be clear, seem complete, and describe friendly syntax... and be wrong. The docs for Math::Matrix, for example, fail to describe a very useful feature -- that the objects have a number of overloaded operators. Somebody just reading the docs and not the code wouldn't be able to tell. (Reminds me; I never got around to writing a bug-report on that.)

It's possible for modules to even have example code in their docs that doesn't run -- something undetectable without actually installing the module. This is what Pod::Tests and other similar modules are for, but not everybody (myself included) uses them.

Warning: Unless otherwise stated, code is untested. Do not use without understanding. Code is posted in the hopes it is useful, but without warranty. All copyrights are relinquished into the public domain unless otherwise stated. I am not an angel. I am capable of error, and err on a fairly regular basis. If I made a mistake, please let me know (such as by replying to this node).

Replies are listed 'Best First'.
Re^2: Perldocs and peer reviews
by g0n (Priest) on Jan 31, 2005 at 14:25 UTC
    The problem with that is that it's possible for the docs to be clear, seem complete, and describe friendly syntax... and be wrong

    Which of course a doc review would not highlight. But normal testing and use would.
    I'm not advocating POD review as a replacement for functional testing, but as a way to get more people involved in distribution QA in a way that is easier and more accessible than performing full blown testing, and getting a 'first pass' done on a wider range of modules.
    After all, full testing on every module on CPAN is well nigh impossible, but if we could get a POD review on a wider range, that would be better than nothing.


Log In?

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

How do I use this? | Other CB clients
Other Users?
Others avoiding work at the Monastery: (4)
As of 2016-09-25 23:35 GMT
Find Nodes?
    Voting Booth?
    Extraterrestrials haven't visited the Earth yet because:

    Results (474 votes). Check out past polls.