Re: PLEASE: standard package README file/orientation
> From: Rogerio Brito <rbrito@iname.com>
> On Aug 19 2000, John Ackermann wrote:
> > I heartily agree with Daniel's plea. Eveb a simple listing of what
> > configuration files the package uses (and where they are), and where it
> > stores data (i.e., does it use space in /var) would be a big help.
>
> All packages *do* already have such files. Documentation files
> for package <package> are intended to be in the
> /usr/share/doc/<package> directory. ...
>
> If a given package doesn't do this, then this particular
> package has a bug (but not the Distribution as a whole).
>
> Frankly, this is a pretty standard thing and many people would
> want it. Why would you think the packages don't have such an
> important feature?
Why? Because of all the times I've needed such information and it
wasn't there or was hard to find.
Some packages don't have a documentation directory at all.
Some others do but their files are so scrambled that you can't
tell which are current, which are obsolete (because of, e.g.,
Debian clean-up of how the package works), etc., without
reading each file.
Look, all I'm asking for is basic "starting-point" documentation
(a brief mention of what you might want to do with the package,
and pointers to existing documentation on how to configure and
use it) in a standard place (a known file name to look for in
/usr/share/doc/<package>/).
PLEASE remember what changes, especially for the user installing
the software, between building and installing from source
tarballs vs. installing distribution packages:
When building from source, you have a README file with build
and installation instructions (because it's obvious enough
to authors that users need a README file to know how to build
and install the software easily). Installation includes
configuration, so that's usually mentioned in the README file.
Installation README files typically conclude with pointers to
what you can do with the software (e.g., "now you should be
able to run the xyz command") and documentation (e.g., "for
more details see 'man pdq.conf").
The main thing is that at the point right after you've installed
the software, you aren't left hanging; you've been following
some script, and it usually winds down with pointers to what to
do next. (Even it doesn't, it typically started with some
orientation to what the software is in the first place.)
When you install a package, on the other hand, building and
installation are already handled, so, of course, you don't
need the building and installation parts of a traditional README
file.
However, the nothing in the package installation system handles
pointing the user to what can be done next with the just-installed
software. Therefore, packages still need to provide the orientation
or what-to-do-next part of a traditional README file.
Debian packages don't provide that orientation reliably at all.
Source tarballs usually provide the primary README file in a known
or clearly recognizable place (./README or ./INSTALL). The user
knows where to look, and can distinguish that file from others
lying around the same directory (wasting much time figuring out
which is which).
Packaged software should also provide its primary README file in
a known place. We do have directory /usr/share/doc/<package>/
(well, for some packages), but there doesn't seem to be a standard
file name for the primary README file so you can recognize it
without wading through the various files that might be in that
directory.
(Maybe that standard file name is supposed to be README.Debian,
but that certainly isn't there reliably (e.g., its exists only 71
of the 216 package installed here). Several of those files _do_
point to configuration or explain what's different on Debian, but
others do not.)
Not that I want to hold up anything on MS Windows as positive,
but think about how a typical(?) installer works:
After installing its software, it leaves the Start Menu subfolder
open (to tell you what applications or utilities you can run), and
opens the read-me file.
Instead of simply exiting after installation and leaving you
hanging, wondering what new applications or utilities you can
invoke, it gives you a(n admittedly crude) pointer to those
programs (the Start Menu subfolder), and also gives you a
starting point (the read-me file) for using the software.
I'm certainly not saying that Debian should use those methods
or anything close (besides, they wouldn't work for installing
multiple packages at once); I'm just pointing out that those
installers don't leave the user hanging after installation.
Daniel
--
Daniel Barclay
dsb@smart.net
(Hmm. A little worrisome: http://www.junkbusters.com/cgi-bin/privacy
http://www.anonymizer.com/snoop.cgi )
Reply to: