bannera

Book A.
Introduction

Book B.
7150 Requirements Guidance

Book C.
Topics

Tools,
References, & Terms

SPAN
(NASA Only)

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Migration of unmigrated content due to installation of a new plugin


{alias:SWE-115} {tabsetup:1. The Requirement|2. Rationale|3. Guidance|4. Small Projects|5. Resources|6. Lessons Learned} {div3:id=tabs-1} h1. 1. Requirements
Wiki Markup
Tabsetup
1. The Requirement
1. The Requirement
12. Rationale
23. Guidance
34. Small Projects
45. Resources
56. Lessons Learned


Div
idtabs-1

1. Requirements

5.2.7.1

The

Software

User

Manual

shall

contain:

\

[SWE-115

\

]

a.

    Software

    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

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

h2. {color:#003366}{*}

1.1

Notes{*}{color} NPR

Notes

NPR 7150.2,

NASA

Software

Engineering

Requirements,

does

not

include

any

notes

for

this

requirement.

h2.

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.

{applicable:asc=1\|ansc=1\|bsc=1\|bnsc=1\|csc=*\|cnsc=0\|dsc=*\|dnsc=0\|esc=*\|ensc=0\|f=*\|g=*|h=0|} {div3} {div3:id=tabs-2} h1. 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."{sweref:373} 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. {div3} {div3:id=tabs-3} h1. 3. Guidance _{floatbox}In accordance with


applicable
f*
g*
h0
ansc1
asc1
bnsc1
csc*
bsc1
esc*
cnsc0
dnsc0
dsc*
ensc0



Div
idtabs-2

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

sweref
373
373
 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.


Div
idtabs-3

3. Guidance


Floatbox

In accordance with NASA-STD-8719.13,

Software

Safety

Standard

{

sweref

:

271
271

}

,

"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." {floatbox}_ \\ 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

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

{

sweref

:047} For NASA flight projects, the Software User Manual is baselined by the Operational Readiness Review

047
047
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."{sweref: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}; 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} * 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} * 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}, 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} * 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. # Resources --- discussion, high-level diagrams, and tables for system and subsystems. ## Hardware. ## Data definitions, i.e., data groupings and names. ## Peripheral space considerations --- data storage and printout. ## Memory considerations --- program storage, array storage, and data set buffers. ## Timing considerations. ### Central Processing Unit time in terms of samples and cycles processed. ### Input/output time in terms of data sets used and type of processing. ### Wall-clock time in terms of samples and cycles processed. # Run information --- control statements for various processing modes. # 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} * Summary of history of system development, operation, maintenance.{sweref:063} * System in which software is intended to be used or in which the software is a part.{sweref:063} * Project sponsor, acquirer, user, developer, and support agencies.{sweref:063} * Current and planned operating sites.{sweref:063} * Quick reference guide. * Glossary of terms, acronyms, and abbreviations. \\ {note}Consult Center Process Asset Libraries (PALs) for Center-specific guidance and resources, such as templates, related to software user manuals and their contents. {note} Additional guidance related to Software User Manuals may be found in the following related requirement in this Handbook: | [SWE-077|SWE-077] | Deliver Software Products | \\ {div3} {div3:id=tabs-4} h1. 4. Small Projects No additional guidance is available for small projects. The community of practice is encouraged to submit guidance candidates for this paragraph. {div3} {div3:id=tabs-5} h1. 5. Resources {refstable} {toolstable} {div3} {div3:id=tabs-6} h2. 6. Lessons Learned No Lessons Learned have currently been identified for this requirement. {div3} {tabclose}

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.


Note

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




Div
idtabs-4

4. Small Projects

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


Div
idtabs-5

5. Resources


refstable

toolstable


Div
idtabs-6

6. Lessons Learned

No Lessons Learned have currently been identified for this requirement.