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 <[EMAIL PROTECTED]>, http://people.debian.org/~debacle/ -- To UNSUBSCRIBE, email to [EMAIL PROTECTED] with a subject of "unsubscribe". Trouble? Contact [EMAIL PROTECTED]