What should be in a CPAN distro README?

综合编程 2015-01-12

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.

责编内容by:brian d foy (源链)。感谢您的支持!

您可能感兴趣的

How to remove leading zeros in a string in Linux? H ow to remove leading zeros in a variable or a string? Let us c...
Deprecation warnings now tell you when the feature... Perl v5.28 will have better deprecation warnings. Most of this I picked up from...
Perl – 6 examples to fetch date / time witho... H ow to fetch date and time related stuff within in Perl? Sometimes, P...
Perl 6系列(4)- Whatever 本来下一步想讲的是正则表达式和Grammar的,刚好后面@Tison 菊苣的两篇文章就把Grammar给覆盖了(所以后面系列提到Grammar的时候直...
正则表达式高级用法 引子 上一章分享了正式表达式的入门知识,以及单字符、多字符常用的匹配方法,对于工作维护过程中已经够用,但是有时候只使用基础知识来实现就会比较麻烦,如果...