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?

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.

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.