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

NPR 7150.2,

NASA

Software

Engineering

Requirements,

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.

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

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

  sweref
  047 047

• 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"

  sweref
  063 063

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

  sweref
  063 063

• Conventions – meaning of colors in displays, audible alarms, abbreviations, and any other conventions used in the software; "rules for assigning names or codes."

  sweref
  063 063

• 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)"

  sweref
  047 047

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

  sweref
  063 063

• 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"

   sweref
   047 047

• Summary of history of system development, operation, maintenance.

  sweref
  063 063

• System in which software is intended to be used or in which the software is a part.

  sweref
  063 063

• Project sponsor, acquirer, user, developer, and support agencies.

  sweref
  063 063

• Current and planned operating sites.

  sweref
  063 063

• 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: