Most of my README
s 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, README
s 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?
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.