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 [EMAIL PROTECTED] (Hmm. A little worrisome: http://www.junkbusters.com/cgi-bin/privacy http://www.anonymizer.com/snoop.cgi )
