What should be in a CPAN distro README?
Most of my READMEs are lame. I have stuff that no one will really ever use. As I'm cleaning up my distros, I starting thinking about what should be in there. To do that, I have to think about the people who would read such a thing.
A long time ago in an internet far, far away, READMEs were small documents that you could inspect before you committed to the full download. After that, we neglected them for a long time. Then GitHub started formatting them, so now they are interesting again.
But who would read them?
Some people turn the embedded module documentation into text and put that in the README, but that's so much easier to get on CPAN Search or MetaCPAN.
I don't think people read the file to get installation instructions or to discover my email address.
Looking around CPAN, I saw that I wasn't doing so poorly relative to everyone else. We, as a group, keep this thing around without really making it useful.
People who read README are probably there because they don't know where else to look and haven't experienced a Perl distribution. If that's the case, then those are the people I should write to. I should explain the important files, but also point them to the resources that everyone else is using.
Rather than reproduce on here, see an example in my unreleased CPAN::Critic README.pod. I'm sure there's more I can put in there.
I ran across some GitHub repo checker website tool a couple of weeks ago, but I can't remember what it was called or where I found it. I put my repo URL in the text box and it told me what I was missing (like a CONTRIBUTING file). Does anyone know what I was looking at.
I'm the author of Mastering Perl, and the co-author of Learning Perl (6th Edition), Intermediate Perl, Programming Perl (4th Edition) and Effective Perl Programming (2nd Edition).
It is still so. "Download" expanded to "checking out the repo", "sinking time into it for further investigation", though.
I agree the full documentation replicated is not helpful. OTOH the first paragraph from the description most likely is, as it tells the potential user whether he should bother with the package or not.
The data say otherwise. http://cpants.perl.org/kwalitee/has_readme
Having a README doesn't make it useful, and I doubt many people actually read what we provide, especially when so many better resources are available.
I tend to just use the readme to mirror the main pod docs. Since I stick everything on github that makes it easy for anyone that is looking on github to figure out what the module is about. on the other hand I was thinking maybe it would be better if it have more install instructions or something.
README files (IMO, and in general - not Perl specific) have been the thing that explains what a directory contains, and what to do to make it useful (e.g. build instructions).
I have been doing some playing with node modules recently, in that space the README files generally are quite useful giving a description of the module and some comments on installing and usage description. This isn't as useful for CPAN modules as we have good documentation in metacpan where as npm.org is somewhat lacking (go POD).
When I have come to trying to contribute to the node or perl modules though I tend to be looking at github not metacpan or npm.org so their better README is helpful. I have noticed the fondness of dzil users to not have README files is some what depressing though (dzil is a system that needs lots of explaining for a dzil newbe to get started)
I liked this idea a great deal. So much so that I adopted it in the Git::Hooks module.
However, after releasing it I got a pull request explaining that there are some problems in keeping a README.pod file at the root of my distribution because it will be installed in the wrong place. (In my case, as Git::README instead of Git::Hooks::README.)
One solution would be to rename it to README.md and replace POD with Markdown, but it seems a little odd to use MD instead of POD in a Perl module. :-)
I've looked at some of your distributions and noticed that you have already inserted README.pod files in some of them, but I couldn't find one released yet to find out if you have solved this problem. Have you thought about this yet?