bannera

Book A.
Introduction

Book B.
7150 Requirements Guidance

Book C.
Topics

Tools,
References, & Terms

SPAN
(NASA Only)

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 13 Next »

Error formatting macro: alias: java.lang.NullPointerException
SWE-115 - Software User Manual
Unknown macro: {div3}

1. Requirements

5.2.7.1 The Software User Manual shall contain: [SWE-115]

a.    Software summary, including:  application, inventory, environment, organization, overview of operation, contingencies, alternate states, and modes of operation, security, privacy, assistance, and problem reporting.
b.    Access to the software:  first-time user of the software, initiating a session, and stopping and suspending work.
c.    Processing reference guide:  capabilities, conventions, processing procedures, related processing, data back up, recovery from errors, malfunctions, emergencies, and messages.
d.    Assumptions, limitations, and safety-related items/concerns or constraints.
e.     Information that is unique or specific for each version of the software (e.g., new and modified features, new and modified interfaces).

1.1 Notes">1.1 Notes

NPR 7150.2 does not include any notes for this requirement.

1.2 Applicability Across Classes

Classes C-E, safety critical are labeled with "SO".  This means that the requirement applies only for safety critical portions of the software.

Class F and Class G are labeled with "X (not OTS)".  This means that this requirement does not apply to off-the-shelf software for these classes.

Class

  A_SC 

A_NSC

  B_SC 

B_NSC

  C_SC 

C_NSC

  D_SC 

D_NSC

  E_SC 

E_NSC

     F      

     G      

     H      

Applicable?

   

   

   

   

    X

   

    X

   

    X

   

    X

    X

   

Key:    A_SC = Class A Software, Safety Critical | A_NSC = Class A Software, Not Safety Critical | ... | - Applicable | - Not Applicable
X - Applicable with details, read above for more | P(C) - P(Center), follow center requirements or procedures

Unknown macro: {div3}

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"1.  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.

Unknown macro: {div3}

3. Guidance

Per the _ NASA Software Safety Standard_, "Operational documentation, including user manuals and procedures, shall describe all safety related commands, data, input sequences, options, and other items necessary for the safe operation of the system....All error message descriptions and corrective actions shall be included in operational documentation."

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 should 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 prior to software system testing so that the manual can be verified during this test phase for accuracy and completeness. Per the "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."3 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; software's purpose and background; benefits from use of the software
  • Inventory – 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, 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"3
  • 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 input is accepted, rate of output, response time, error rate); "relationship of the functions performed by the software with interfacing systems, organizations, or positions"4; supervisory controls that are available to manage the software
  • Contingencies, alternate states, modes of operation – list and description of modes in which software operates (e.g., normal, emergency, critical, launch, on-orbit) along with available and restricted operations, 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 should 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, 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 should provide the following reference information:

  • Capabilities – "the interrelationships of the transactions, menus, functions, or other processes"4
  • Conventions – meaning of colors in displays, audible alarms, abbreviations, and any other conventions used in the software; "rules for assigning names or codes"4
  • 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)"3, 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 online 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"4
  • Data back-up – steps the user should perform to backup 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 should perform if an error condition occurs in the software; steps to ensure continuity of operations in the event of an emergency
  • Messages – list of informational, diagnostic, error, 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 should describe 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, new and modified interfaces.  The author should 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
  • a. 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
                       (a)  CPU time in terms of samples and cycles processed
                       (b)  I/O time in terms of data sets used and type of processing
                       (c)  Wall-clock time in terms of samples and cycles processed
  • b. Run information — control statements for various processing modes
  • c. 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"3
  • Summary of history of system development, operation, maintenance4
  • System in which software is intended to be used or in which the software is a part4
  • Project sponsor, acquirer, user, developer, and support agencies4
  • Current and planned operating sites4
  • Quick reference guide
  • Glossary of terms, acronyms, and abbreviations

Consult Center Process Asset Libraries (PALs) for Center-specific guidance and resources, such as templates, related to software user manuals and their contents.

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

[SWE-077]

Deliver software products


Unknown macro: {div3}

4. Small Projects

There is currently no guidance for small projects relevant to this requirement.

Unknown macro: {div3}

5. Resources

  1. NASA Procedural Requirements, "External Release of NASA Software w/Change 1", NPR 2210.1A, 2004.
  2. NASA Technical Standard, "NASA Software Safety Standard", NASA-STD-8719.13B, 2004.
  3. NASA Software Engineering Laboratory, "Recommended Approach to Software Development", Revision 3, SEL-81-305, 1992.
  4. Glenn Research Center, "Software User Manual (SUM) Template", GRC-SW-TPLT-SUM, 2011.
  5. IEEE Computer Society, "IEEE Standard for Software User Documentation", IEEE STD 1063-2001, 2001.  A user account is needed to access IEEE standards via this NASA Technical Standards System link.
  6. IEEE Computer Society/EIA Standards Project, "Trial-Use Standard, Standard for Information Technology Software Life Cycle Processes Software Development Acquirer-Supplier Agreement", J-STD-016-1995, Annex J.2.1, 1995. A user account is needed to access IEEE standards via this NASA Technical Standards System link.

5.1 Tools

Please reference table XYZ in this handbook for a list of tools in use at NASA that may be relevant to this requirement.  Note that this table should not be considered all-inclusive, nor is it an endorsement of any particular tool.  Check with your Center to see what tools are available to facilitate compliance with this requirement.  

Unknown macro: {div3}

6. Lessons Learned

There are currently no Lessons Learned identified for this requirement.

  • No labels