PLEASE: standard package README file/orientation
Why don't all Debian packages come with installation instructions
in a _standard_ place that tell you what you need to do (after
installing the package) to configure or use the package you just
loaded?
There needs to be a standard place to consult to know what a
package needs (setup) and what it provides (e.g., commands the
user can now run).
PLEASE think about what happens right after users install a
package:
They know the name of the package.
They don't necessarily know the name of any commands, other
executables, or configuration files provided by the package.
Therefore, they can't use any of those names to try to find any
manual pages for those the package.
(Remember that package names frequently don't match command names.
Consider package ppp providing executable pppd, and pilot-link
providing pilot-xfer, etc., but no pilot-link.)
The only name the users know for sure is the name of the package.
Since the users do know that name, they can go to
/usr/share/doc/<packagename> to look for any setup instructions,
for orientation to what they can do, or pointers to other
documentation (e.g., manual pagse).
(Note that even if a package runs a configuration command during
installation, a mention of that configuration command is still
needed in the doc directory: Users need to know what command to
run if later they want to reconfigure things.)
There needs to be root documentation for each package that contains
or points to information on:
- setting up the package or changing the setup,
- using the package (e.g,. what commands in provides, or what
daemons will be running)
- separate configuration packages and add-on packages
(e.g., lpr's orientation file would mention magicfilter)
- signficant differences from the upstream version of the package.
How about something like this?:
Define (as part of the Debian package policies) a file in
/usr/share/doc/<package>/ with a standard name (maybe use
README.Debian consistently, or something like ORIENTATION).
Have a setup/configuration section that mentions any manual
steps needed to set up the package and pointers to other
documentation on that setup. If setup was done automatically
during installation, mention how to re-configure the package.
Have a section on using the package that mentions commands,
daemons, libaries/functions, documentation, etc., provided by
the package.
Please think about a typical README file for component distributed
in source form:
After telling you how to build and install the component, it
typically tells you:
- what you have to do to configure your installation,
- what you should be able to do with it (what commands you can
now run), and
- where the documentation is (the names of manual or info pages or
of other files).
Now, consider documentation needs when using automatic package
installation:
It's true that we don't need the build or base installation
instructions.
However, we _do_ still need the configuration instructions and
the pointers to provided commands and documentation. Otherwise,
how can users know how to use the just-installed software?
PLEASE consider requiring some "starting point" documentation
for packages.
(Note that this isn't MS Windows, where you install one thing at a
time, and where it can leave a Start Menu folder open on your desktop
to give you a hint about what new commands you can run. (Not that
that's a _good_ orientation or pointer, but it's something.)
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: