Re: README - confusing, irrelevant, redundant, useless

[Ben Armstrong <synrg@sanctuary.nslug.ns.ca>]

On Mon, 2005-08-15 at 16:31 +0200, Henning Makholm wrote:
> I don't think there is a way to get around this difference. There is a
> fairly widespread convention of putting compilation instructions in an
> INSTALL file, but there is no similarly widespread convention for
> putting information about, say, "you'll need these libraries", "here
> is what this program can be used for" or "here is how tarball users
> should report bugs" in other files than README.

I'm just struggling with how to strike a happy medium between best
practices for Debian and best practices for upstreams.  I don't believe
it is in our best interests to, as some have suggested, copy the useful
README info into README.Debian.  It's just going to drift out of date
with changes made by upstream.

> In general, I would assume that *most* of the README files we ship in
> .debs could be dropped without ill effects. In the cases where it
> actually contains text that is useful for end-users as well as
> significant text that isn't, it might be worth a try to approach
> upstream about separating the *useful* stuff out as a file that is
> *different* from README.

Yes, that's what I'm driving at.  I've seen some nice multi-level
READMEs that provide a few notes for compiling the package up front
(which is what most people look at a README in a tarball to find out)
and just put "see" references for the rest, segregated into README.foo
files that deal with different topics.

> However, trying to move traditional README information *away* from
> README just so that we can ship the useful text easily under the name
> README would appear to be a lost cause. Note that there is no
> requirement that documentation in the .deb has to be named README at
> all.

Understood, and agreed.

Ben