README - confusing, irrelevant, redundant, useless

["W. Borgert" <debacle@debian.org>]

Hi,

I have to start yet another discussion about our packaging
practise.  Did anyone ever take a look at our
/usr/share/doc/<package>/README{,.gz} files?  If the users have
difficulties with a package, we often reply "Why didn't you read
the README?  It's called README for a reason!"  However, the
README files are cluttered with confusing, irrelevant,
redundant, and useless stuff.  That way, we educate our users
not to ReadTheFineReadme.

Do you think, that this does any favour to our users?  E.g.

- "Debian packages of this software are currently available.
  It should be possible to run "apt-get install <package>" and
  have a recent version installed."

  This is a Debian package, so what?

- "Please send bug reports, requests for features, etc. to
  <upstream-mail-address>."

  Don't we ask our users to use our BTS primarily?

- "To build <package>, please run: ./configure; make; make
  install."

  This is OK to have in the source, but not in the .deb.  Same
  goes for information about possible configuration options.
  OTOH, the configuration options actually used in the Debian
  package are seldomly documented :-(

- ...long history of who maintained the package when...

  This information - not really relevant to the user - is, of
  course, in the changelog as well.

- ...stuff about API usage in a library package...

  That does belong to the -dev package only, right?

- "Common options: --foo --bar --baz"

  According to our policy, the program has a manual page.  While
  it's not bad, to repeat the information in other formats, it
  does - IMHO - not make sense in a README.

- "Readme file for <package>."

  Really?

- "This program is..." - exact copy of the package description.

  This README is redundant.

- "$Id: ... $" (one line Id plus four lines of text)

  Maybe I become picky, but CVS/RCS ids are not relevant to the
  user, esp. if the remainder of the README is irrelevant, too.

- "The latest version of <package> can be obtained at <upstream
  website>."

  As a Debian user, I expect to get packages the Debian way.
  It's nice to have the upstream website address, but according
  to our policy I can find it in the copyright file.

Package maintainers, please:

1. Do not include the upstream README in the binary package, if
   it's not really important to the user.

2. Just copy the 5..10% of relevant information into the
   README.Debian, if appropriate.

3. Don't invent a README file artificially, if you don't have
   to say anything.

4. File minor bugs about such README files.

Cheers,
-- 
W. Borgert <debacle@debian.org>, http://people.debian.org/~debacle/