"The good news about computers is that they do what you tell them to do. The bad news is that they do what you tell them to do."
-- unsure; often attributed without source to information philosopher Ted Nelson
Every software package should have extensive documentation.
Every program should accept the standard command line arguments --help and --usage (optionally having short forms -h and -?). Both should behave similarly: as soon as the argument is detected, the program should ignore the rest of the arguments, print a message to stdout, then exit successfully without performing its normal function.
When invoked with --help, the program should print brief documentation for how to invoke the program, and specify a method for reporting bugs. For example:
% hello --help Usage: hello [options] file... Options: --help or -h Display this message --usage or -? Display brief summary of command-line arguments --version or -V Display program version --message=TEXT Message to display (default "Hello, World!") --output=FILE Redirect output to file (default stdout) Report bugs to nobody@nowhere.com.
When invoked with --usage, the program should print a message briefly showing available command-line options. For example:
% hello --usage Usage: hello [--help] [--usage] [--version] [--message=MESSAGE] [--output=FILE]
Many programs, especially non-interactive command-line programs, provide options to determine the level of output. The "--quiet" and "--silent" options (which if used, should both be supported, and be equivalent) suppress all normal messages. The "--verbose" option turns on additional messages not normally displayed.
Documentation for the package should be included in the "doc/" subdirectory.
Every software package should have a User's Guide. If the package includes more than one program, they can each have their own User's Guide or be documented together in a single User's Guide, depending on whether they are likely to be used together or not. If the documentation has its own license different from the package, it should be included in a plain text file COPYING in the documentation directory, and can be included in the guides themselves as well.
Each guide should include sections for:
In addition, the User's Guide should have (after the known bugs):
There are many different possible formats for documentation, including:
DocBook is useful because it can be converted into all the other common formats, and because it is the standard for the GNOME project.
Every program should have a Unix man page, even if it only tells where to find full documentation elsewhere, or is generated from the DocBook source. More than one program can be documented on a single man page if they are always used together and the man page is short.
The software package installation should provide options for generating guides in whatever formats are available.
Every graphical program should include a Help menu as the last item on its menubar. The Help menu should include at least the following:
The first menu item should be "User's Guide" which pops up a help browser displaying the user's guide.
The last menu item should be "About" which pops up a dialog with the program's name, version, copyright status and a very brief description.
Optionally, the Help menu may also include an item for opening an Internet browser to the package's Internet site.
If possible, each software package should have an Internet presence. An Internet presence could include:
E-mail address(es) for contacting the developers, reporting bugs, asking for help, etc. (most important)
A Web site containing contact information, what Internet resources are available, a brief description of the software package, any publicly available documentation for the software package, and any publicly available distribution of the software package. (desirable)
An FTP site with similar information as the Web site, but in plain text rather than HTML format. (not particularly important these days)
Other tools for helping users such as mailing lists and IRC channels. (important only if you have a very large user base and the resources to implement this)
Ideally, a computer security expert should evaluate the package for security concerns, which should be listed in the documentation.