Re: README - confusing, irrelevant, redundant, useless
Benjamin Seidenberg <astronut@dlgeek.net> writes:
>
> I think a better solution would be to duplicate all the important
> information about the software into the README.Debian and train users
> to read that soley.
If I was king of the world (or at least of Debian), I would go the
more radical route of renaming all upstream READMEs (which, as
W. Borgert points out, are of highly variable quality and often the
*last* thing a new user should be reading) to README.upstream.gz and
mandating the inclusion of a README.gz file of reasonably standard
form using existing README.Debian files as a starting point.
At a minimum, the README.gz file should include a brief package
description, an overview of what's included in the package, a "quick
start" section explaining how one is expected to get started using the
package (or at least a pointer to the upstream's "quick start"
documentation), and possibly some maintainer's notes at the bottom
explaining any special compilation options or patches included in the
Debian version.
Of course, it should be Debian-centric, telling the user how to get
started with *this* package, not a freshly built upstream version. If
I don't have to copy "foo.cf-EXAMPLE" from the build directory to
"/usr/local/etc/opt/share/bar/foo.cf" to use this package, it
shouldn't be mentioned.
Now, this is the role that README.Debian is usually trying to play,
but not all packages include it, and even when they do, sometimes the
file is just a Debian maintainer sending out mad props out to his
peeps ;) or, more realistically, *only* explaining how the Debian
package differs from the standard upstream package and not giving the
kind of "quick start" stuff I'm thinking about.
Really, I can't count the number of times I've downloaded a package
and then had to resort to searching for binaries and manpages listed
in its "/var/lib/dpkg/info/*.list" file to figure out how to use it.
--
Kevin Buhr <buhr+debian@asaurus.net>
Reply to: