Suggestion: Post-installation README file
Could you all please consider this suggestion for a standard
post-installation read-me file?
This is something I was reminded of on the Debian-Java list:
------- Start of forwarded message -------
...
Date: Thu, 9 Sep 1999 00:16:39 -0400 (EDT)
From: Daniel Barclay <daniel@dsb.smart.net>
...
To: debian-java@lists.debian.org, debian-devel@lists.debian.org
...
[slightly edited]
...
You know, I wonder if automatic package installation has gone slightly
too far.
I think something has been forgotten: pointing users to whatever they
might need and/or want to do after installing a package.
When you install from a tar file, there's README file. After the
installation instructions, it usually mentions what you can do next.
(E.g., it typically mentions the commands provided be the software;
whether the documentation is manual pages, info pages, other files;
etc.)
On the other hand, when you install a package, once the package is
installed, you're kind of left with nothing.
Think about it: You find out about a package and install it on your
system. Now what? What do you do next? How do you know which commands
or user-level files it provides?
There no standard /usr/doc/<package>/README (or README.debian) that
you can count on. There is nothing (standard) pointing to commands or
user-level files provided by the package, or pointing to documentation.
(When there is a file /usr/doc/<package>/README, it's usually from the
original source release and doesn't apply to Debian's binary packaging
of the software.)
Maybe each Debian package should have a standard post-installation README
file that:
- mentions what the package provides (e.g., commands available to be run,
daemons started, files (e.g., debian-doc) provided.)
(Note that the name of a package isn't always related the command(s) it
provides, so a mention of commands or files x and y from package z would
frequently be helpful. )
- refers to configuration options that you're likely to want to change
or confirm
(I'm not suggested much redundancy with other documentation; just
pointers to things that are especially import or that users are
especially likely to want to know about up front.)
- points to relevant documentation (manual, info, or web pages loaded
by the package, or on-line documentation, etc.)
(Because documentation be provided in many forms, it is scattered about
and the user has to check many possibilities (e.g., man <command name>,
man <package name>, man <config. file name>, info <command name>,
/usr/doc/<package name>/.../*.html, /usr/doc/<package_name>/*.txt.gz,
http://..., etc. A standard starting place would be a lot more
convenient and efficient.)
- * points out significant Debian-specific changes to the package
(so if you knew the unpackaged version of the software, you can
know what's different (I'm thinking of Debian's Netscape wrapper that
wasted a lot of my time because its changed behavior wasn't documented))
Generally, the post-installation README file would be a guide to getting
on with using the just-loaded package that could be found easily in a
known location (/usr/doc/share/<package>/README or .../DocRoot or
somewhere).
Daniel
--
Daniel Barclay
dsb@smart.net
Reply to: