User documentation

10.4 User documentation

The best software is not useful if the end user does not know how to use it. User documentation may include not only the user manuals, but also maintenance, operator, training, and other project specific documents, such as the version description document. User documentation provides instructions to the end user of the software system. It addresses proper preparation and presentation of inputs, operating instructions, and directions for the interpretation of the output data. It may also present operating instructions, training needs, descriptions of differences from one version to the next, and maintenance information.

User documentation shows and tells the user how to make use of the software system. It should discuss the system, specify the format and content of the inputs, and describe the outputs that are the result of the system processing.

The software quality practitioner must take an active role in the review and evaluation of the user documentation. If the software cannot be used properly, it matters little if it is a quality product. The user documentation must make proper use possible. Software quality practitioners should make a test run of the user manual to see if the instructions make it possible to actually use the system as it was meant to be used. This can sometimes be made a part of the final acceptance or demonstration testing or may be an individually conducted exercise. The important thing to be accomplished is the verification that the user documentation does make proper operation and use of the software possible.

10.4.1 Input requirements

With respect to input, the user documentation will tell the user what information is required by the system. It will present data formats, ranges of legal values, schedules of input, and other information concerning the input data. Such things as methods of input (e.g., hardware registers, keyboard entries, data from other systems), where the data are to be submitted (e.g., dial-up access, via a terminal), when the input is required (e.g., every Thursday, when prompted), and other appropriate information specific to the particular system must be available to the user in the user manual.

10.4.2 Output description

Another important part of the user documentation is instructions on how to interpret the results of the processing. Full descriptions of all outputs are necessary. The documentation must, of course, contain instructions on how to understand the displays or printouts that are created. In addition, it must provide a complete and understandable description of all nonstandard outputs such as error messages, abnormal halts, loss of system sanity, and so on. Each of these situations or outputs will be described and the proper response spelled out. If the system is running in a central or remote data center, instructions for the distribution of hard-copy output will be provided.

10.4.3 Operation instructions

The user documentation should include the operation instructions, as well as pure user information; that is, the details on how to actually make the system operate. Such information as how to load the system, what storage media are required, special peripherals such as high-speed printers or mass storage devices that are to be on-line, and how to bring the system down when processing is complete may be included in the operators' instructions. Whether this information is in the user manual or in a separate document is usually a function of the size of the system and where it is run (e.g., on a desktop computer or in the central data center). Some installations may have documentation standards that specify where this information is to be provided.

An operator manual or similar document is often needed for complicated systems that require the involvement of computer center personnel. This involvement may be the mounting of tapes and disk packs, handling of output forms or reports, sequencing of several systems into the proper executional order, and so on. Many systems are self-sufficient once they are initiated. In those cases, there may be few or no operator instructions. Larger systems may however, justify a separate operator manual to provide detailed information concerning the operation of the software system.

The software quality practitioner is responsible for reviewing operator documents for format and required content both at the initial release and during the operation and maintenance phases of the SLC.

10.4.4 Maintenance

Good maintenance documentation helps keep the software running and up-to-date. Whoever is responsible for the maintenance of the software should prepare a software maintenance plan. The primary tool of the software maintainers is the body of software documentation. Without clear and complete documentation of the software, the maintainers must recreate the data on which they will base enhancement and correction actions. Of course, the single most important document is the listing of the source and corresponding object code of the software. Without this, the maintainer must work backwards from the object code to recreate the source code or must work in object code itself.

The next most important document is the final design description (or as-built) document discussed in Section 10.2.2.3. This document, or its equivalent, together with the up-to-date requirements and flowcharts or processing diagrams, explains to the maintainer exactly what the software is supposed to contain and how it is constructed. It is with these documents that maintainers study defect reports and requests for system enhancements. The flow diagrams (in whatever form is the standard for the specific installation) and the as-built design document present the software system design and implementation and describe what it does and how it does it. The requirements describe the full environment into which the change must fit.

The maintenance portion of the user documentation contains information of importance to the persons who are to maintain the software system. This portion usually contains the as-built design information (see Section 10.2.2.3), descriptions of phased implementation modifications made and pending (see Section 7.4.1.4), records of software changes made since implementation (see Section 6.4), and the like. Anything that will make the work of the software maintainer easier is appropriate for inclusion in the maintenance portion of the user documentation.

In the evaluation of maintenance documentation, software quality practitioners must be sensitive to the environment of the maintainer and the documentation needs involved. Reviews of the maintenance documentation should be attended by and heavily influenced by representatives of the maintenance organization. Deficiencies noted in the maintenance documentation will then be brought to the attention of management for resolution.