There seems to be a consistent body of thought that every module should have a README. Indeed the CPANTS Kwalitee mavens score you a point for this.

But, what should this file contain? In many cases, it is the output from pod2text run against the primary module.pm. While this could be useful to a newbie who does not know how to use perldoc, this is of limited use for experienced Perl users. Also, it means that the documentation is now in two places in the distribution, which can potentially get out of step.

The boilerplate output from module creation tools (apart from insulting the author for being too lazy), does include the mantra:

perl Makefile.PL
make
make test
make install

[download]

With a footnote to use nmake for Windows. To me, this is extremely useful information for the Perl beginner.

Should this information appear somewhere in the pod, perhaps under =head1 INSTALLATION? Is it something that we all take for granted anyway? Maybe it belongs in a separate file called INSTALL.

Which returns to the original question. What should go in the README file? What is its intended audience and purpose?

--

Oh Lord, won’t you burn me a Knoppix CD ?
My friends all rate Windows, I must disagree.
Your powers of persuasion will set them all free,
So oh Lord, won’t you burn me a Knoppix CD ?
(Missquoting Janis Joplin)

In reply to What should be in the README for a module? by rinceWind

Title:
Use:  <p> text here (a paragraph) </p>
and:  <code> code here </code>
to format your post, it's "PerlMonks-approved HTML":


  • Posts are HTML formatted. Put <p> </p> tags around your paragraphs. Put <code> </code> tags around your code and data!
  • Titles consisting of a single word are discouraged, and in most cases are disallowed outright.
  • Read Where should I post X? if you're not absolutely sure you're posting in the right place.
  • Please read these before you post! —
  • Posts may use any of the Perl Monks Approved HTML tags:
    a, abbr, b, big, blockquote, br, caption, center, col, colgroup, dd, del, details, div, dl, dt, em, font, h1, h2, h3, h4, h5, h6, hr, i, ins, li, ol, p, pre, readmore, small, span, spoiler, strike, strong, sub, summary, sup, table, tbody, td, tfoot, th, thead, tr, tt, u, ul, wbr
  • You may need to use entities for some characters, as follows. (Exception: Within code tags, you can put the characters literally.)
            For:     Use:
    & &amp;
    < &lt;
    > &gt;
    [ &#91;
    ] &#93;
  • Link using PerlMonks shortcuts! What shortcuts can I use for linking?
  • See Writeup Formatting Tips and other pages linked from there for more info.