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

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]

I want the most common or two errors you'll get as well as solutions to them. Also a brief overview about installing it on other platforms.

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.

Comment on Re: What should be in the README for a module? Download Code

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