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.

    VGhpcyBtZXNzYWdlIGludGVudGlvbmFsbHkgcG9pbnRsZXNz
[reply]

In Section Meditations