Re: Re: CPAN documentation improvements

You see, that's my issue. I feel that the CPAN people who accept module submissions should 'raise the bar' on documentation requirements. That way, if you are looking at a module on CPAN, you get at least a certain quality of documentation.

The proposition that author(s) do not have the time to write documentation but do have time to write a module is silly. I would say the ratio of code to documentation is 10:1 (for every 10 hours coding you would probably use < 1 hour documenting). Tell me if I am wrong.

The benefit to improving standards is pretty obvious. Documentation and tutorials are not the same thing! I would be happy to write a tutorial which highlights certain interesting features of a module, but documenting every single feature is boring and tedious, which is probably why the original authors fail to do it. But since somebody has to do it and noone is probably better at it than the author I think the standard for CPAN submission should be in place.

Celebrate Intellectual Diversity

Comment on Re: Re: CPAN documentation improvements

Replies are listed 'Best First'.
Re3: CPAN documentation improvements by bikeNomad (Priest) on Jul 02, 2001 at 20:23 UTC
I view CPAN as being like a box of mixed chocolates... The argument you're making is equally valid for other aspects of code quality. There are CPAN modules without adequate test packages, modules that have unnecessary version dependencies, and (of course) modules with bugs in them. And, as you say, there are modules that aren't documented well (or at all). One might as well say that nothing should get into CPAN without a test suite that can be shown to have 100% coverage, or until after an explicit peer review. On the other hand, no one is forcing you to use CPAN modules, and you still might get usable code or at least ideas from the submissions. There is a self-serving reason for CPAN authors to write documentation, of course; if you have a popular module, you'll get a lot less email to deal with if you add documentation. My own modules are pretty well documented (Archive::Zip: 27% pod, Algorithm::Diff: 54% pod) but I still get questions asking me about various things. I try to address these questions in the next version of the documentation so that I don't have to answer the same emails again. Then too, just because you have documentation in a module doesn't mean that people will read it (as evidenced by the number of answers here on PM that quote one bit or another from the manual).	[reply]

Replies are listed 'Best First'.

Re3: CPAN documentation improvements
by bikeNomad (Priest) on Jul 02, 2001 at 20:23 UTC

The argument you're making is equally valid for other aspects of code quality. There are CPAN modules without adequate test packages, modules that have unnecessary version dependencies, and (of course) modules with bugs in them. And, as you say, there are modules that aren't documented well (or at all).

One might as well say that nothing should get into CPAN without a test suite that can be shown to have 100% coverage, or until after an explicit peer review.

On the other hand, no one is forcing you to use CPAN modules, and you still might get usable code or at least ideas from the submissions.

There is a self-serving reason for CPAN authors to write documentation, of course; if you have a popular module, you'll get a lot less email to deal with if you add documentation. My own modules are pretty well documented (Archive::Zip: 27% pod, Algorithm::Diff: 54% pod) but I still get questions asking me about various things. I try to address these questions in the next version of the documentation so that I don't have to answer the same emails again.

Then too, just because you have documentation in a module doesn't mean that people will read it (as evidenced by the number of answers here on PM that quote one bit or another from the manual).

[reply]