7.1.2 The Command Reference

The Command Reference section of a manual includes detailed descriptions of each command, including seldom-used information such as keyboard equivalents, hidden options, maximum and minimum sizes of data objects, etc. This information will be most useful to more experienced users who are pushing your system to its limits. It will also be turned to by system administrators who are trying to understand problems that arise in systems they support. Many users, however, will never need the Command Reference section. It shouldn't be required to complete the reference tasks on which your task-centered design has focussed, and it is the first section you should eliminate for smaller systems.

Because the Command Reference is a system-oriented view of the interface, it may be the easiest section for you, the designer, to write. You still need to write for the user, but now you're writing for a user with more experience, so the presentation can be more technical. It's often effective to use a standard, tabular format for each command, which might list the command name, its effect, a description of options and parameters, and any warnings or limitations. Keep the entire description as brief as possible.

The organization of the Command Reference section is problematic. With command-line interfaces, the section is typically alphabetical by command name. For graphical interfaces, one option is hierarchical, following the menu hierarchy: look under File to find New, then look within that section to learn about the New dialog box. This is workable with shallow hierarchies (File...New...dialog box), but it becomes cumbersome with more deeply nested menus (File...Save...New...dialog box). For such systems, an alphabetical organization may again be more useful.