I wonder if there are any plans to add greater restrictions/requriements for documentation of CPAN modules? There are several that I have looked at that are substantially lacking in documentation. Take this one for example. If you click on the README link, you get a lot less documentation than you would normally expect. I am looking forward to other people's views on this.

Celebrate Intellectual Diversity

Replies are listed 'Best First'.
Re: CPAN documentation improvements
by BMaximus (Chaplain) on Jun 30, 2001 at 02:28 UTC
    The README file should only have the a synopsis of what the module does and a simple explanation of how to install it if an INSTALL file isn't present. Its the job of the documentation within the module that should explain usage. Having that explanation in the README file is rather redundant in my opinion. CPAN extracts the POD from the module and creates a page that can be viewed on their site for more information. You should be looking there for usage rather than the README file.

    It's up to the author of the module or those who take part in its creation to properly document it. Going through some of the modules on CPAN I do see that some of the documentation provided with them is very poor. While others provide an explanation that allows a user to get it right the first time without mucking around.

    BMaximus
[reply]
Re: CPAN documentation improvements
by bikeNomad (Priest) on Jun 30, 2001 at 03:52 UTC
    Well, per your tagline (Celebrate Intellectual Diversity), perhaps there are people who would enjoy writing CPAN documentation. I imagine that most CPAN authors would gladly incorporate an accurate, well-written document, translation, or tutorial written by a user. I know I would. If you spend your time figuring out a package, why not write up a quick tutorial and send it to the author?
[reply]
      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

[reply]
        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]
Re: CPAN documentation improvements
by Another Lee (Initiate) on Jul 02, 2001 at 14:38 UTC
    Doesn't the CPAN documentation on what a README file should be explicitly state it is a minimal file, not a POD? If you want fuller documentation, read the POD. If you have real problems, why not mail the author? He's a friendly enough chap. - The Author (lgoddard@CPAN.org)
[reply]

Back to Meditations