Re^2: What should be in the README for a module?

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)

Comment on Re^2: What should be in the README for a module?

Replies are listed 'Best First'.
Re^3: What should be in the README for a module? by neosamuri (Friar) on Oct 11, 2005 at 21:14 UTC
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.	[reply]

Replies are listed 'Best First'.

Re^3: What should be in the README for a module?
by neosamuri (Friar) on Oct 11, 2005 at 21:14 UTC

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.

[reply]