What should be in a CPAN distro README?

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.

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.

稿源:brian d foy (源链) | 关于 | 阅读提示

本站遵循[CC BY-NC-SA 4.0]。如您有版权、意见投诉等问题,请通过eMail联系我们处理。
酷辣虫 » 综合编程 » What should be in a CPAN distro README?

喜欢 (0)or分享给?

专业 x 专注 x 聚合 x 分享 CC BY-NC-SA 4.0

使用声明 | 英豪名录