bannera

Book A.
Introduction

Book B.
7150 Requirements Guidance

Book C.
Topics

Tools,
References, & Terms

SPAN
(NASA Only)

SWE-049 - Document Software Requirements

1. Requirements

3.1.1.1 The project shall document the software requirements.

1.1 Notes

The requirements for the content of a Software Requirement Specification and a Data Dictionary document are defined in Chapter 5 [of NPR 7150.2, NASA Software Engineering Requirements, section 5.2.1 and 5.2.2, respectively]. The requirements definition activity also includes documenting key decisions, developing requirement rationales, and defining assumptions. The requirement development activities can use lessons learned in performing the logical decomposition process activities. The requirements definition activity provides an understanding of the derived technical requirements baseline, a logical decomposition model, traceability to technical requirements, and an understanding of the stakeholder's expectations.

1.2 Applicability Across Classes

Class E and Not Safety Critical is labeled with "P (Center)."  This means that an approved Center-defined process which meets a non-empty subset of the full requirement can be used to achieve this requirement.

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?

   

   

   

   

   

   

   

   

   

    P(C)

   

   

   

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

2. Rationale

Requirements are the basis for a software product. They identify the needs to be addressed, the behavior of the system, and the constraints under which the problem is to be solved. They specify the product the provider is to deliver to a customer.

Clearly defined, well written, and accurately captured requirements "reduce the development effort because less rework is required to address poorly written, missing, and misunderstood requirements." 273  Well-written requirements also provide "a realistic basis for estimating project costs and can be used to evaluate bids or price estimates" and "provide the stakeholders with a basis for acceptance of the system." 273

Requirements serve as the basis for verification activities allowing the developing organization and the customer to judge the completeness of the product.

3. Guidance

A general process flow for documenting software requirements is shown below:

Guidance for the content of the documents which capture software requirements, the Software Requirement Specification (SRS) (SWE-109) and the Data Dictionary document (SWE-110) are found in other sections of this Handbook.  Additionally, software interface requirements may be captured in an Interface Control Document (ICD) or an Interface Requirements Document (IRD), along with hardware interface requirements. If an ICD or IRD is used, the SRS references that document.

The following roles may be involved in defining and documenting software requirements as appropriate for the project:

  • Project stakeholders, including the customer and senior management.
  • Software Lead.
  • Software Requirements Engineer.
  • Systems Engineer.
  • Software Architects.
  • Software Assurance Engineer.

Elements to Capture
When capturing software requirements, it is important to:

  • Document key decisions and the person(s) who made them, for example:
    • Which requirements are "must-have."
    • Prioritization of requirements.
    • Stakeholder decisions that form the basis for requirements.
    • Resolutions to conflicting requirements.
    • High-level design choices that affect low-level requirements.
  • Develop requirement rationales, for example:
    • Reasons why one feature or performance requirement was chosen over another.
    • Originating document or basis for a requirement, e.g., operational concepts document, trade study, parent requirement.
    • Stakeholder expectations.
    • Risks which are the basis for a requirement.
    • Technology limitations.
    • Time constraints.
    • Regulations, laws.
  • Define assumptions, for example:
    • Environmental or any other constraints.
    • Mission type  (e.g., human-rated vs. robotic).
    • Assumed technology availability.
    • Preset budgetary restrictions.
  • Logically decompose the requirements.

  • Notes on decomposition:
    • System requirements are general requirements; allocated, flowed down requirements are more detailed as the levels progress.
    • Decompose or partition the system into finer and finer (more detailed) elements (into a functional, physical, data driven, or object-oriented hierarchy); each element in this hierarchy has its own requirements that work together to meet the higher-level requirements allocated to that requirement. 178
    • All top-level requirements must be allocated to at least one element at the next level and have at least one flowed down requirement associated with it at that lower level. 178
    • The Software lead works with the Systems lead to identify system requirements that are allocated to the software development effort.
    • Examine each top-level requirement to identify the software requirements necessary to accomplish that requirement and fulfill the function it describes.
    • After systems engineers allocate system requirements to subsystems, such as the software subsystem, software engineers develop the requirements for those elements.
    • Identify "input, output, and processing needed to satisfy the high-level requirements using structured, object-oriented, or another analysis method focusing on what the software needs to do rather than specific 'how-to' details." 049
    • Decompose requirements into a "set of make-to, buy-to, code-to, and other requirements from which design solutions can be accomplished." 273
    • Lowest level may be module level for software. 178
    • Typically an iterative process as successive lower-level functional and performance requirements are defined at ever-increasing levels of detail; this can point out additions, changes, deletions that need to occur in parent requirements. 178
    • Iteratively repeat allocation and requirements development (flow-down) at each successive lower level.
       
    • May need to revise parent requirements as new information is obtained at the lower, more detailed levels 178
    • Maintain link to parent requirement (i.e., lower-level requirements need to support requirements at the next higher level and it may be helpful to document in the rationale what the lower-level requirement does to support the parent requirement). 046
    • Derived requirements will be created during this process; derived requirements are requirements that differ from the parent requirement, but state a capability the lower-level element (subsystem or lower) must have to meet the parent requirement. 178
    • Consider constraints (e.g., cost, standards, regulations).
    • Decomposition may be based on or influenced by a project hierarchy for the software subsystem.
    • Resolve requirements conflicts.
    • Lessons learned from previous decomposition activities may be helpful; the Requirements Engineering 178 article also provides a good overview of requirements allocation and flow-down.

Information Sources
"Software Requirements Definition involves eliciting, producing, and analyzing customer, product, and product component requirements." 001 Inputs to this process may include:

  • System and subsystem requirements documents, hardware schematics and specifications.
  • System architecture.
  • System models and simulations.
  • System safety analyses, including the preliminary hazard analysis (PHA), subsequent system hazard analyses, and software safety analyses.
  • Environmental requirements, including operations and hardware requirements, vehicle or facility requirements.
  • Standards.
  • External regulations.
  • Program/project specification.
  • Operational concepts document.
  • Interface requirements.
  • Legacy products.
  • Organizational requirements.
  • Quality attributes (e.g., reliability, availability, security, safety, maintainability, portability, usability).
  • Structured interviews with customers, users (may include development of scenarios, examination of reports, analysis of competing products), other subsystem engineers (e.g., electrical/electronic and data; thermal; Guidance, Navigation, and Control (GN&C); mechanical).
  • Brainstorming sessions with customers, users, developers.
  • Stakeholder input or user needs (provided or elicited via interviews, prototypes, questionnaires, surveys, or other techniques).

General Guidance
Some general guidance to follow when defining and documenting software requirements includes:

  • Provide a unique identifier for each requirement.
  • Express requirements as "shall" statements (avoiding words like "could," "should," "must," and "will").
  • Clearly identify software safety requirements.
  • Structure requirements so they are:
    • Complete, correct, consistent.
    • Traceable.
    • Independent.
    • Unambiguous.
    • Modifiable.
    • Understandable.
    • Necessary.
    • "Clear, precise, unequivocal, verifiable, testable, maintainable and feasible." 271
  • Refine the initial set of requirements into a manageable set (e.g., remove duplicates, remove unnecessary requirements, combine requirements, clarify requirements, keep "must-haves", drop some "nice-to-haves").
  • Have requirements reviewed by stakeholders (to identify and address ambiguous, conflicting, incomplete requirements; peer reviews/inspections is one technique).
  • Capture software requirements in the required documents and in a requirements management tool for easy access, manipulation, and management; some tools may allow for generation of the requirements documents directly from the tool.
  • State the requirements, not how to fulfill them (i.e., avoid including design decisions in the requirements).
  • State only one requirement per statement (i.e., avoid compound requirements).

Common Problems
Defining and documenting requirements is not a simple task.  According to Kandt, Ronald Kirk, Jet Propulsion Lab, "Software Quality Improvement, Software Requirements Engineering: Practices and Techniques", (JPL Document D-24994, 2003) 061, common problems that occur during or because of this activity and which are to be avoided, include:

  • Failing to define needed requirements, including safety requirements.
  • Writing requirements inconsistently or ambiguously.
  • Using inexperienced personnel to define the requirements.
  • Incorrect understanding of underlying assumptions or constraints.
  • Including unneeded features or capabilities.
  • No clear method for allocating requirements to software subsystems.
  • Choosing solutions before defining the requirements and/or user needs.
  • Failing to spend enough time or resources on requirements definition.

Consult Center Process Asset Libraries (PALs) for Center-specific guidance and resources related to documenting software requirements, including templates, checklists, and sample documents.

Guidance for baselining and updating the SRS in preparation for life-cycle milestone reviews can be found in Topic 7.8 - Maturity of Life Cycle Products at Milestone Reviews in this Handbook.

Additional guidance related to documenting software requirements may be found in the following related requirements in this Handbook:

SWE-050

Software Requirements

SWE-051

Software Requirements Analysis

SWE-052

Bidirectional Traceability Between Higher Level Requirements and Software

SWE-053

Manage Requirements Change

SWE-109

Software Requirements Specification


4. Small Projects

"Any project with resource limitations must establish the relative priorities of the requested features, use cases, or functional requirements. Prioritization helps the project manager plan for staged releases, make trade-off decisions, and respond to requests for adding more functionality. It can also help you avoid the traumatic 'rapid de-scoping phase' late in the project, when you start throwing features overboard to get a product out the door on time." 358

5. Resources

5.1 Tools

Tools relative to this SWE may be found in the table below. You may wish to reference the Tools Table in this handbook for an evolving list of these and other tools in use at NASA. 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.

Tool nameTypeOwner/SourceLinkDescriptionUser

RequirementsLink

COTS

ENSER/Parametric Technology Corporation (PTC)

http://www.ptc.com/appserver/wcms/relnotes/note.jsp?icgdbkey=826imdbkey=119829 ...

Windchill RequirementsLink. Requirements capture and tracking tool. Windchill RequirementsLink - an integral option for Windchill PDMLink - lets you manage product requirements, including change control and associating requirements with specific product structures and design content. With bi-directional traceability between customer needs, market requirements and the underlying technical requirements, you can ensure that customer and market requirements are satisfied by designs, and properly verified during development.

SSC

PTC Integrity

COTS

PTC

http://www.ptc.com/application-lifecycle-management/integrity/lifecycle-manager ...

PTC Integrity is a systems and software lifecycle management (SSLM) and application lifecycle management (ALM) platform used for Process automation and workflow management

IV&V, GSFC

Enterprise Architect

COTS

Sparx Systems, Inc.

http://www.sparxsystems.com/ ...

Enterprise Architect provides complete traceability from requirements, analysis and design models, through to implementation and deployment. ...

IV&V

DOORS®

COTS

IBM® Rational®

http://www-01.ibm.com/software/awdtools/doors/ ...

IBM® Rational® DOORS® family is a group of requirements management tools that allow you to capture, trace, analyze and manage changes across the development lifecycle.

ARC, DFRC, GRC, GSFC, IV&V, JPL, JSC, JSC, LaRC, MSFC,

6. Lessons Learned

The NASA Lessons Learned database contains the following lessons learned related to defining and documenting software requirements:

  • Flight Software Engineering Lessons (Developing a complete set of requirements.) Lesson Number 2218: Recommendation No. 7 states: "Development of a complete and consistent set of engineering requirements requires a robust systems engineering process that defines performance and resource utilization requirements, traces requirements to higher and lower-level requirements, ensures review of requirements by key stakeholders and by parties independent of the engineering of the requirements, and assesses the requirements using a checklist of questions that address quality concerns." 572
  • Lessons Learned From Flights of "Off the Shelf" Aviation Navigation Units on the Space Shuttle, GPS (COTS/GOTS/MOTS software.) Lesson Number 1370: "Define 'must meet,' 'highly desirable' and 'nice to have' requirements. Ability of the unit to meet those requirements, and at what cost, will be a major deciding factor in the COTS decision." 551
  • Software Requirements Management (Customer role in requirements definition.) Lesson Number 3377: A lesson learned was that "Additionally, a collaborative relationship between the customer using the software and the developer providing the software is paramount to the success of the software project. More specifically, the users/customers must effectively define and accurately communicate their requirements to the developer. For example, the user's defined requirements should be clearly stated and unambiguous, concise, complete, autonomous, able to be implemented, and testable." 576
  • Probable Scenario for Mars Polar Lander Mission Loss (1998) (Include hardware requirements.) Lesson Number 0938: As part of the probable scenario for Mars Polar Lander Mission Loss, a lesson learned was that "All known hardware operational characteristics, including transients and spurious signals, must be reflected in the software requirements documents and verified by test." 529
  • Chandra X-ray Observatory (CXO) Development Program Programmatic "Lessons Learned" (Stable requirements key to program stability.) Lesson Number 0987:  A lesson learned was that "Stable Requirements are key to program stability. Do not allow requirements to creep. One step in this process is to involve all stakeholders in developing and finalizing requirements. Stakeholders may include potential development and operations contractors, engineering and other organizations and NASA Headquarters." 531
  • Chandra X-ray Observatory (CXO) Development Program Programmatic "Lessons Learned" (Involve operation and systems engineering.) Lesson Number 0987:  One recommendation is to "Include operations in requirements definition and early design...Do not overlook the need for strong systems engineering involvement in requirements and verification traceability." 531
  • The Pitfalls of "Engineering-by-Presentation" (2005) (Formal requirements documentation.) Lesson Number 1715:  The Abstract states: "Formal documentation of requirements, resolutions, and decisions -- including maintaining records of the basis and justification for each engineering decision -- was once a standard NASA practice. The increased use of informal records such as presentation slides and e-mail may be inhibiting the ability of NASA programs and projects to reference technical decisions and to validate or verify engineering designs." 566