Stories
Slash Boxes
Comments
NOTE: use Perl; is on undef hiatus. You can read content, but you can't post it. More info will be forthcoming forthcomingly.

All the Perl that's Practical to Extract and Report

The Fine Print: The following comments are owned by whoever posted them. We are not responsible for them in any way.

README 3 Comments More | Login | Reply /

 Full
 Abbreviated
 Hidden
More | Login | Reply
Loading... please wait.
  • The README should not include your module's documentation. That's what the embedded POD is for. The README should not include installation instructions. That's what the INSTALL file is for.

    Your README should definitely not consist solely of module installation instructions.

    Man, you're just going to love this particular example then.

    There's this module that just got uploaded on CPAN. The README with it contains... well: nothing. Nothing at all, except what h2xs put there as an example, I think. Christ. I mean, it might be an excellent module, I don't know. It's hard to find out, this way.

    See for yourself:

    README for Petal [cpan.org]

    • I know. What do you think prompted my rant? :) [This is by no means the first module to do this.]

      I think h2xs shouldn't say that the README should include installation instructions, because I don't think that's where those instructions should go. Or, at least, they should be shoved down at the bottom under the "Why do I want to use this module?" part.

      Petal is sort of a bad name for a module, too. Great name for a program. Maybe it's a huge configuration management system. Maybe it's an automatic d

      --
      J. David works really hard, has a passion for writing good software, and knows many of the world's best Perl programmers
    • Well whatdayaknow... 3 days later, and there is a new upload for Petal (uploaded yesterday), and this one does have a proper readme file...
      Readme for Petal 0.3 [cpan.org]

      Not only that, but by the looks of it, the module does indeed look very interesting. And now, we can know about it.

Stories, comments, journals, and other submissions on use Perl; are Copyright 1998-2006, their respective owners.