2. Rationale

Very few software projects result in a product that users understand and can use efficiently, completely, and successfully without some guidance.  Software documentation "explains the capabilities of the software or provides operating instructions for using the software to obtain the desired results." ³⁷³ Along with software and other documentation, the final delivered package for software projects, including contracted projects, includes operational instructions for the delivered software. These instructions are typically provided by a Software User Manual, which contains both user instructions and a description of the functions and features provided by the software.

3. Guidance

Software User Manuals are written with the user in mind.  Software User Manuals may be used as tutorials, introductions to the software, or just as reference guides. Regardless of how often the user will pick up the manual, it needs to be complete, accurate, and written with easy-to-find information that is concise, yet detailed enough to be clearly understood. Depending on the intended audience, it may also be helpful to organize the manual by tasks that the user is expected to perform using the software.

The Software User Manual is typically created before software system testing so that the manual can be verified during this test phase for accuracy and completeness. In accordance with SEL-81-305, Revision 3, Recommended Approach to Software Development, "The development team begins preparation of the user's guide during the implementation phase... A draft is completed by the end of the implementation phase and is evaluated during system testing. At the beginning of the acceptance test phase, an updated version is supplied to the acceptance test team for evaluation. Corrections are incorporated, and a final revision is produced at the end of the phase." ⁰⁴⁷ For NASA flight projects, the Software User Manual is baselined by the Operational Readiness Review (ORR).

A complete user manual contains a summary of the software; instructions for starting and using that software; a processing reference guide; assumptions, limitations, and safety information; and any information unique to this version of the software.  Assistance for completing each of these elements of a Software User Manual is provided below.

Software summary

The software summary provides an overview of the software, including:

• Application – explanation of specific tasks for which the software is intended; the software's purpose and background; benefits from use of the software.
• Inventory – a list of all elements included in the software package; elements required to successfully install and run the software, including databases and data files.
• Environment – hardware, e.g., computer equipment and communications equipment; other software, e.g., operating systems, databases, utilities, data files; physical conditions; and setup necessary for the successful operation of the software and in which the software was designed to operate. If applicable, include "high-level diagrams of system showing hardware interfaces, external data interfaces, software architecture, and data flow." ⁰⁴⁷
• Organization –  user's perspective of software organization; logical components with purpose and operation relevant to the user as opposed to the developer.
• Overview of operation – summary of the features and functions available from the software, including displays, windows, menus, reports, and system performance considerations; performance characteristics, e.g., rate of input that is accepted, rate of output, response time, error rate; "relationship of the functions performed by the software with interfacing systems, organizations, or positions" ⁰⁶³; supervisory controls that are available to manage the software.
• Contingencies, alternate states, modes of operation – a list and description of modes in which software operates, e.g., normal, emergency, critical, launch, and on-orbit, along with available and restricted operations and functions in each mode; differences between normal operation and operation in times of emergency.
• Security and privacy – description of security and privacy considerations associated with the software, including, as applicable, making unauthorized copies of the software.
• Assistance – contact information when assistance is needed to operate the software.
• Problem reporting – steps to perform to report a software problem for correction.

Access to the software

The software access portion of the user manual needs to be written for a first-time user of the software and provide instructions for:

• Initiating a session – obtaining a password, changing a password, starting the software, logging in, and any other steps to begin using the software.
• Stopping and suspending work – steps for saving work, logging off, shutting down, and any other steps for cleanly ending a session.
• Equipment familiarization – powering on the system, expected initialization screens, and expected user  responses/actions, using the keyboard and pointing device, powering down the system.
• Installation and setup – equipment setup; loading software; system initialization, including files, variables, and data; tailoring and reconfiguration; re-initialization.
• Software access under abnormal conditions – determining if abnormal termination occurred; restarting after abnormal termination; recovery procedures, as applicable.
• Security and privacy for storing and marking reports generated by the system.

Processing reference guide

The processing reference guide needs to provide the following reference information:

• Capabilities – "the interrelationships of the transactions, menus, functions, or other processes." ⁰⁶³
• Conventions – meaning of colors in displays, audible alarms, abbreviations, and any other conventions used in the software; "rules for assigning names or codes." ⁰⁶³
• Processing procedures – "Detailed description of processing keyed to operator-specified input and actions in terms of points of control, functions performed, and results obtained (both normal and abnormal, i.e., error processing and recovery)" ⁰⁴⁷, including:
  • Purpose of menus, functions, transactions, processes.
  • Step-by-step procedures.
  • User inputs.
  • User commands, including data entry, save, print, update, and delete; and operation cancellation, interruption, and restart.
  • Expected results.
  • Images of menus, icons, forms, diagnostic messages, as applicable, with explanations.
  • Software navigation.
  • Help or information for accessing on-line help.
  • If appropriate, a tutorial.
• Related processing – "identify and describe any related batch, offline, or background processing performed by the software that is not invoked directly by the user and is not described in [processing procedures]...user responsibilities to support this processing shall be specified." ⁰⁶³
• Data backup – steps the user is to perform to back up any data collected or generated by the software such that it can be used to replace data in case of system error.
• Recovery from errors, malfunctions, emergencies – steps the user is to perform if an error condition occurs in the software; steps to ensure continuity of operations in the event of an emergency.
• Messages – a list of informational, diagnostic, error, and warning messages that can be generated by the software and any associated actions required by the user; may be an appendix that contains this information.

Assumptions, limitations, and safety-related items/concerns or constraints

This portion of the Software User Manual describes any operating assumptions, limitations, constraints, or safety-related concerns not described elsewhere in the manual.  Providing this information allows the user to understand the bounds of the software and its operation, including limitations and safety-related concerns that can be affected by user input and actions.

Information that is unique or specific for each version of the software

Each version of software is unique in some way, e.g., new and modified features and/or new and modified interfaces. It is important for the author to include in the Software User Manual descriptions of the items that make a particular version of software unique from previous versions, if there are previous versions of the software.

Additional content

Additional content to consider for inclusion in the Software User Manual includes:

• Identifying information for the software, such as software name, system name, identification number, version number, release number, release date, issuing organization.
• High-level description of input and output.

1. Resources — discussion, high-level diagrams, and tables for system and subsystems.
   1. Hardware.
   2. Data definitions, i.e., data groupings and names.
   3. Peripheral space considerations — data storage and printout.
   4. Memory considerations — program storage, array storage, and data set buffers.
   5. Timing considerations.
      1. Central Processing Unit time in terms of samples and cycles processed.
      2. Input/output time in terms of data sets used and type of processing.
      3. Wall-clock time in terms of samples and cycles processed.
2. Run information — control statements for various processing modes.
3. Control parameter information — by subsystem, detailed description of all control parameters, e.g., NAMELISTs, including name, data type, length,  representation, function, valid values, default value, units, and relationship to other parameters" ⁰⁴⁷

• Summary of history of system development, operation, maintenance. ⁰⁶³
• System in which software is intended to be used or in which the software is a part. ⁰⁶³
• Project sponsor, acquirer, user, developer, and support agencies. ⁰⁶³
• Current and planned operating sites. ⁰⁶³
• Quick reference guide.
• Glossary of terms, acronyms, and abbreviations.

Additional guidance related to Software User Manuals may be found in the following related requirement in this Handbook:

4. Small Projects

No additional guidance is available for small projects. The community of practice is encouraged to submit guidance candidates for this paragraph.

5. Resources

5.1 Tools

Tools to aid in compliance with this SWE, if any, may be found in the Tools Library in the NASA Engineering Network (NEN).

NASA users find this in the Tools Library in the Software Processes Across NASA (SPAN) site of the Software Engineering Community in NEN.

The list is informational only and does not represent an “approved tool list”, nor does it represent an endorsement of any particular tool. The purpose is to provide examples of tools being used across the Agency and to help projects and centers decide what tools to consider.

6. Lessons Learned

No Lessons Learned have currently been identified for this requirement.