...

...

3. Guidance

Software requirements have their basis in customer requirements, system level parent requirements and operational concepts. Decomposition of these higher-level requirements and concepts is required to develop and document the requirements for software. Clearly defined, well-written, and accurately captured requirements reduce "costly redesign, remanufacture, recoding, and retesting in later life-cycle phases."

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.

A general process flow for capturing, approving, and maintaining software requirements is shown below:

Image Removed

According the NASA Systems Engineering Handbook, requirements "...are decomposed in a hierarchical structure starting with the highest level requirements imposed by Presidential directives, mission directorates, program, Agency, and customer and other stakeholders. These high-level requirements are decomposed into functional and performance requirements and allocated across the system. These are then further decomposed and allocated among the elements and subsystems. This decomposition and allocation process continues until a complete set of design-to requirements is achieved. At each level of decomposition (system, subsystem, component, etc.), the total set of derived requirements must be validated against the stakeholder expectations or higher level parent requirements before proceeding to the next level of decomposition. The traceability of requirements to the lowest level ensures that each requirement is necessary to meet the stakeholder expectations. Requirements that are not allocated to lower levels or are not implemented at a lower level result in a design that does not meet objectives and is, therefore, not valid. Conversely, lower level requirements that are not traceable to higher level requirements result in an overdesign that is not justified."

The flow down of requirements

Image Removed

This flow addresses requirements development via the nominal system flow down process. However, software requirements can also be developed/matured with the system (i.e., in spiral/incremental/agile fashion), especially when software plays a key role in the integration and buildup of the system. Refer to reputable life-cycle reference documents (see also SWE-019) for further discussion of this type of requirements development.

Requirements identification, development, documentation

Requirements are typically documented in a Software Requirements Specification (SRS) and a Data Dictionary document. 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. Guidance for the content and development of these documents, including requirements identification and development based on operational concepts and customer and stakeholder requirements, is located in Topic 7.18 – Documentation Guidance.

The following roles may be involved in establishing and documenting software requirements, including quality 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.

Projects that use modeling and simulation as part of the development process may choose to develop and document requirements using models or both text and models. Requirements captured as "text descriptions cannot be computer interpreted because they are in natural language text. They will remain ambiguous because natural language is not precise. The use of models augments the text forms by providing computer executable and transformable information that is free from ambiguity and needed by the engineers who will design according to the specifications."

Requirements documentation includes bidirectional traceability through the software life-cycle phases. See guidance in SWE-052, SWE-059, SWE-064, and SWE-072 for discussion of requirements traceability.

...

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

Image Removed

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

  Swerefn
  refnum 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.

  Swerefn
  refnum 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 an analysis method focusing on what the software needs to do rather than specific 'how-to' details.
• Decompose requirements into a "set of make-to, buy-to, code-to, and other requirements from which design solutions can be accomplished."

  Swerefn
  refnum 273

• Lowest level may be module level for software.

  Swerefn
  refnum 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.

  Swerefn
  refnum 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

  Swerefn
  refnum 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).
• 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.

  Swerefn
  refnum 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 

  Swerefn
  refnum 178

  article also provides a good overview of requirements allocation and flow-down.

Information Sources

Defining software requirements involves eliciting, generating, and analyzing customer, product, and product component requirements. 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).

...

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

  • Measurable.

  • Quantitative.

  • "Clear, precise, unequivocal, verifiable, testable, maintainable and feasible."

    Swerefn
    refnum 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

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

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

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.

Requirements approval

Requirements review and approval is necessary to ensure that they accurately capture user needs and project goals and objectives.  Once requirements are identified, developed, and documented, they are evaluated, analyzed (SWE-051) and  approved in light of stakeholder requirements and operational concepts by one or more of the following, based on project procedures:

• Project management: Approves formalized requirements (as documented in the SRS, Data Dictionary, and/or ICD, IRD).
• Customer/Stakeholders: Approve formalized requirements.
• Systems engineering: Reviews software requirements under direction of project management.
• Software assurance: Audits the requirements document(s) against software assurance requirements.
• Review board: A milestone review, such as the Software Requirements Review (SwRR),  a Technical Exchange Meeting (TIM) or both, is conducted; if both are performed, the TIM should precede the SwRR.

Changes from any of these reviews or approval processes should be incorporated into the software requirements before they proceed to the next step in the project life cycle.  Approved requirements are baselined and maintained in the project’s configuration management system.

Requirements maintenance

Maintenance of software requirements is needed because they typically change throughout the project based on information and experiences obtained during the project life cycle.

Managing requirements change is a critical aspect of requirements maintenance because changes to requirements can be an indicator of software instability and often mean increased costs, longer schedules, rework and can affect software safety. Guidance for SWE-053 addresses managing requirements change throughout the project and guidance for SWE-054 addresses correcting inconsistencies among requirements and project products.

It is important that requirements be updated in the requirements management tool (if one is used) as well as the requirements documents (e.g., SRS, Data Dictionary, ICD, IRD). Those updated requirements are made available to all stakeholders, including developers, testers, managers, and anyone else making decisions or performing work based on software requirements.

Benefits of Well-Written Requirements 

Image Removed

...

"The requirements database is an extremely useful tool for capturing the requirements and the associated metadata and for showing the bidirectional traceability between requirements. The database evolves over time and could be used for tracking status information related to requirements such as To Be Determined (TBD)/To Be Resolved (TBR) status, resolution date, and verification status. Each project should decide what metadata will be captured. The database is usually in a central location that is made available to the entire project team."

NASA-specific software requirements process information and resources are available in Software Processes Across NASA (SPAN), accessible to NASA users from the SPAN tab in this Handbook. 

Additional guidance related to documenting, analyzing, and maintaining software requirements may be found in Topic 7.18 – Documentation Guidance and the following related requirements in this Handbook:

...

5. Resources