Re: README - confusing, irrelevant, redundant, useless
-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1
W. Borgert wrote:
> 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,
While I agree the README can be confusing, I think we do a disservice
to our upstream by not including it. Some readers may be interested in
the people who brought them the software, or knowing upstream's email
or any of these items you mention. As for readme versus man page, I
find manpages are usually more of a reference about syntax while
readme's are closer to a tutorial on usage.
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. The original readme is still intact for those
users who care. In addition, I would like to see a standardazation on
whether to compress the README and similar files, I always end up
typing less /usr/share/doc/blah/README.Debian[.gz] using tab
completion and have to go back and correcting my command to use zless
because half are compressed and half aren't. I also agree with what
Branden said in his WTFM presentation at debconf.. a readme command to
display the readme's to the user would be a very nice tool.
Benjamin
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.1 (GNU/Linux)
Comment: Using GnuPG with Thunderbird - http://enigmail.mozdev.org
iD8DBQFC/3dtev9LOsNKpIQRAkmyAJ9EQMuQCpPOW5P6XtPdGps2sms1mgCgsgEz
eUaQF/vXKll2trd+dU0GXEA=
=/crF
-----END PGP SIGNATURE-----
Reply to: