Suggestion: Post-installation README file

[Daniel Barclay <daniel@dsb.smart.net>]

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