What I look for in a readme file...

First is a brief overview of what the software does.

If there isn't an install file, I look first for how to install the silly thing. I want detailed instructions beyond

perl Makefile.PL
make
make test
make install
[download]

Somewhere there should be a list of all the environmental vars that might affect install (and running but that could be in the man pages or other documentation).

I look for where to go for more extensive help. Who the author is, what email lists discuss it, and other good support places.

There should be something about copyright and what rights the user and author both have.

Everything else I look for in the man pages, which should have some good examples of how to use the software.

I'm generally in favor of have different files for README, INSTALL, COPYRIGHT, etc. I expect each one to have a lot of information rather than some trivial "read the man pages after you have installed" or "I don't have anything in this file yet, check back in the next version." I've seen both statements and they were a sign that I was dealing with buggy software.

First is a brief overview of what the software does.

I look in the pod for a SYNOPSIS or DESCRIPTION paragraph for this.

If there isn't an install file, I look first for how to install the silly thing. I want detailed instructions beyond...

But what if it's a simple module that needs no explanation beyond perl Makefile.PL ... make install? Presumably, the installation does not need mentioning.

I want the most common or two errors you'll get

Do you mean mistakes that the user of the module can make? Or do you mean caveats and bugs in the module? In either case, I think these belong in the pod.

I look for where to go for more extensive help. Who the author is, what email lists discuss it, and other good support places.

This belongs in the pod under SUPPORT.

There should be something about copyright and what rights the user and author both have.

These will either be in the pod under COPYRIGHT and/or LICENSE, or in a separate file called LICENSE.

I know that README files predate pod, but have they been obsoleted by pod?

Here is what I would expect to look for in a README, but I don't see why this couldn't be written in the pod.

• Platform specific information.

I would expect this to be in named files: README.vms, README.mac, README.win32 etc.

• Upgrade issues and API changes.

Over and above the narrative listed in "Changes", should be important considerations when upgrading from one version to another.

• External dependencies

What libraries outside perl are needed? Where can you get them from?

--

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)

Here are a few of my thoughts:

I look in the pod for a SYNOPSIS or DESCRIPTION paragraph for this.

I would still put this information in the README, because the README will most likely be the first thing looked at.

But what if it's a simple module that needs no explanation beyond perl Makefile.PL ... make install? Presumably, the installation does not need mentioning.

For the simple installations I would still put the basic install information. The way I see you can't put to much information into the README, as long as it is well organized. If the README is disorganized it really doesn't matter what is put in it.

I like to use the CPAN shell's readme command to check out unfamiliar modules. I tend to make my first judgement of quality from it.

I like to see:

1. A description of the purpose and scope of the module.
2. Optionally, a comparison to other similar modules.
3. Installation instructions, abbreviated if there is an INSTALL file.
4. A list of prerequisites, both Perl modules and system libraries (important!)
5. Credits: who's writing and patching the module.
6. Contact information, including homepage.

A text copy of the perldoc output is sometimes verbose, but if the pod quality is good it tells me about all I need to know about the module. I'd prefer a shorter specially-written README but I don't hold a doc copy against the module.

I'm not so sure there's One Right Way, but I'll share with you what I personally like: I like to know where the 'HQ' is for that module. By finding out where that module is headquartered, I can probably get the following information directly, (or at least get some good hints):

• Do I have the latest version?
• Any hot bugs not in my version?
• Is there community support? Is it good?
• Any good examples?
• Any recommended 'competitors' or alternatives? <--- this can be a goldmine

So, for me, README is a place not to store the hairy details of a module's installation and use, it's more a place for Meta-Information. A place where I can find out more *about* a module.

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

perlnewmod says

Write the README

If you're uploading to CPAN, the automated gremlins will extract the README file and place that in your CPAN directory. It'll also appear in the main by-module and by-category directories if you make it onto the modules list. It's a good idea to put here what the module actually does in detail, and the user-visible changes since the last release.

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.

Maybe it belongs in a separate file called INSTALL.