Re: README - confusing, irrelevant, redundant, useless
On Sun, Aug 14, 2005 at 12:55:11PM -0400, Benjamin Seidenberg wrote:
> 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
/usr/share/doc/<package>/copyright, according to our policy?
> or any of these items you mention. As for readme versus man page, I
Don't you think that most of the examples I gave are utterly
irrelevant to about 100% of our users, including me and you?
> find manpages are usually more of a reference about syntax while
> readme's are closer to a tutorial on usage.
All my examples show, that a lot of READMEs do not contain
tutorials, but irrelevant information. I did not say anything
against useful information or tutorials in README files. I
personally would prefer a tutorial in a file named, hm, maybe
"tutorial"?
> 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
The name of the file "README" suggests reading its content is
highly important to the user. Sometimes it really is. The huge
number of useless READMEs thwarts that. I still think,
information irrelevant to the user should be removed from the
binary package. If one really cares, apt-get source <package>.
> 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
Doesn't /bin/zless work for both?
> 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.
Yes. Unfortunately, I arrived one day too late for the talk.
Otherwise, I would have criticised Branden for proposing hacking
*roff instead of using DocBook/XML refentries :-)
Cheers,
--
W. Borgert <debacle@debian.org>, http://people.debian.org/~debacle/
Reply to: