bannera

Book A.
Introduction

Book B.
7150 Requirements Guidance

Book C.
Topics

Tools,
References, & Terms

SPAN
(NASA Only)


SWE-056 - Document Design

1. Requirements

3.2.1 The project shall document and maintain the software design.

1.1 Notes

The requirement for the content of a Software Design Description document and an interface design description document are defined in Chapter 5 [of NPR 7150.2, NASA Software Engineering Requirements, section 5.2.3] as applicable by software classification.

1.2 Applicability Across Classes

Classes F and 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

   

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

The software design creates the road map from which the software is coded. Once the requirements for the software are defined, they need to be divided into functional components that can be implemented ("coded") separately, yet work together to fulfill the goals and needs for which the software is being written. The software design defines how to segment the software into components and units, which are useful for modularizing like functionality, reuse, etc. "The process of design provides the structure for converting the requirements into the final code. Where the requirements state what must be done, the design provides how it will be done." 276

The goal is to create "a meaningful engineering representation of something that is to be built...a higher-level interpretation of what will actually be implemented in the source code." 276 This representation, which traces back to the requirements, is the software design.

Per NPR 7150.2, "Software design is the process of defining the software architecture, components, modules, interfaces, and data for a software system to satisfy specified requirements. The software architecture is the fundamental organization of a system embodied in its components, their relationships to each other and to the environment, and the principles guiding its design and evolution. The software architectural design is concerned with creating a strong overall structure for software entities that fulfill allocated system and software-level requirements... Detailed design further refines the design into lower-level entities that permit the implementation by coding in a programming language."

Maintaining the software design (e.g., keeping it current with requirements changes or updated as design decisions are made) is important because the resulting software product reflects what is described in the software design. If that design is not current with the latest requirements or design decisions, the resulting product will be less likely to meet customer expectations. Maintaining design documentation is also important for future maintenance of the operational software because maintenance personnel will use the design documentation to diagnose problems, drive solutions, and figure out how to add new features and functionality. 

3. Guidance

Per NPR 7150.2, "Typical views captured in an architectural design include the decomposition of the software subsystem into design entities, computer software configuration items (CSCI), definitions of external and internal interfaces, dependency relationships among entities and system resources, and finite state machines. ...Typical attributes that are documented for lower-level entities include: identifier, type, purpose, function, constraints, subordinates, dependencies, interface, resources, processing, and data. Rigorous specification languages, graphical representations, and related tools have been developed to support the evaluation of critical properties at the design level. Projects are encouraged to take advantage of these improved design techniques to prevent and eliminate errors as early in the life cycle as possible." Projects can take advantage of existing designs when a similar project has already been completed, use frameworks which provide a base infrastructure on which to build, or be auto-coded using advanced design tools.

Guidance for the content of the documents that capture software design, the Software Design Description (SDD) (SWE-111) and the Interface Design Description (IDD) (SWE-112), are found in other sections of this handbook.

The following roles may be involved in defining, documenting, and maintaining software design:

  • Software Lead.
  • Software engineers.
  • Systems engineers.
  • Software architects.

Capturing the software design

The software design consists of architectural design (SWE-057) and detailed design (SWE-058). When capturing software design, consider the following:

  • Use a defined methodology. such as structured analysis and design, object-oriented analysis and design, model-based development, as appropriate for the software being developed
  • Capture the reasoning behind design decisions (to support future design changes and maintenance). 276
  • Document reuse plans. 047
  • Capture a completed definition of the software architecture 273 (see also Topic 7.7 - Software Architecture Description).
  • Develop a preliminary database design description, as applicable. 273
  • Document the selected operating system and development language. 276
  • Trace software requirements into the design, as well as tracing the design back to requirements (i.e., bidirectional).
  • Define and document the functional interfaces between all components. 276
  • Identify and document shared data within the software. 276
  • Capture the design in a manner that is maintainable (the design needs to be updated as it matures during development and changes through product maintenance efforts).
  • Identify software safety design features and methods used to implement the software safety requirements. 271
  • Capture the IT security features. 072
  • Capture each software subsystem's "software classification (per NPR 7150.2), its safety classification (per NASA-STD-8719.13B, NASA Software Safety Guidebook), the rationale for the classifications" 073; a matrix could be used to capture this information
  • Consider the "Design verification approach, e.g., prototyping, inspection, peer review." 073

Information sources

While the software design is based primarily on the software requirements, the following documents may also influence the software design. As applicable, these documents need to be considered as sources of reasons for design decisions:

  • Operational concepts and scenarios. 001
  • Trade studies. 001
  • System and hardware requirements. 001
  • Processor and communication specifications. 001
  • Hardware design documents, including interface control documents (ICDs) 001
  • Software requirements rationale.
  • Design standards.
  • Design selection criteria (to help choose a design or design element from multiple options).
  • "Sources for design concepts include, but are not limited to, customer input, brainstorming, collective experience and supplier knowledge." 001

Useful Methods and Techniques

The following methods and techniques may be helpful when documenting and maintaining the software design:

  • Structured analysis and design. 276
  • Formal methods and model-based development. 276
  • Functional decomposition and object-oriented design, including the use of design diagrams, structure charts, and associated documentation. 047
  • Design walk-throughs and peer reviews.
  • Design inspections. 047
  • Reuse verification ("determining which of the existing software components specified in the reuse proposal should be integrated into the new system design"). 047
  • Prototyping and demonstrations.
  • Performance modeling. 047
  • Entity relationship models. 157
  • Design patterns. 157

General guidance

Some general guidance to follow when capturing and maintaining the software design includes:

  • Include a legend for any diagrams that assign specific meaning to shapes, colors, line styles, etc.
  • Have the documented design and its updates reviewed at key life-cycle milestone reviews (e.g., Preliminary Design Review (PDR), Critical Design Review (CDR), Test Readiness Review (TRR)).
  • Have the documented design reviewed after it has been updated at any time in the life cycle.
  • Include software safety personnel in the design review process.
  • Update the requirements as design decisions are made, including adding requirements derived from design decisions.
  • Keep the design current with changes to the requirements.
  • Perform software peer reviews/inspections (SWE-087) of the design prior to moving to implementation (coding), as applicable.

The NASA Software Architecture Review Board 323, a software engineering sub-community of practice, is a good resource of software design information including sample documents, reference documents, and expert contacts.

Consult Center Process Asset Libraries (PALs) for Center-specific guidance, templates, and examples related to documenting the software design.

Additionally, guidance related to software design may be found in Topic 7.7 - Software Architecture Description and the following related requirements in this handbook:

SWE-057

Software Architecture

SWE-058

Detailed Design

SWE-111

Software Design Description

4. Small Projects

Projects with limited personnel or budgets may consider capturing the software design using existing design tools, if they are appropriate for the design effort. Additionally, teams can consider the use of software design document templates from the local Center PAL, modifying them as appropriate for the current software design effort. Projects can also take advantage of existing designs when a similar project has already been completed.

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

Together

COTS

Micro Focus

https://www.microfocus.com/products/requirements-management/together/ ...

Together® is a modeling platform that gives enterprise teams leading-edge design capabilities which enable the visualization and continued maintenance of IT architectures.

IV&V

Simulink

COTS

MathWorks

http://www.mathworks.com/products/simulink/ ...

Simulink® is an environment for multidomain simulation and Model-Based Design for dynamic and embedded systems. It provides an interactive graphical environment and a customizable set of block libraries that let you design, simulate, implement, and test a variety of time-varying systems, including communications, controls, signal processing, video processing, and image processing.

IV&V, Stennis, GSFC, ARC, GRC, JPL, MSFC, KSC, JSC

Rational Rose Realtime

COTS

IBM

http://www.interface.ru/rational/rose/rp5.htm ...

IBM Rational Rose Realtime is a Design & code development tool.

GSFC

Rational Requisite Pro

COTS

IBM

http://open-services.net/software/ibm-rational-requisite-pro/ ...

Rational RequisitePro helps project teams to manage their requirements, to write good use cases, to improve traceability, to strengthen collaboration, to reduce project rework, and to increase quality.

GSFC

Quartus Prime

COTS

Intel

https://fpgasoftware.intel.com/ ...

The Quartus Prime software organizes and manages the elements of your design within a project. The project encapsulates information about your design hierarchy, libraries, constraints, and project settings.

LaRC

IBM Rhapsody

COTS

IBM Rational

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

"IBM® Rational® Rhapsody® family provides collaborative design and development for systems engineers and software developers creating real-time or embedded systems and software. Rational Rhapsody helps diverse teams collaborate to understand and elaborate requirements, abstract complexity visually using industry standard languages (UML, SysML, AUTOSAR, DoDAF, MODAF, UPDM), validate functionality early in development, and automate delivery of innovative, high quality products." (NOTE: Several versions are listed on the website for architecture, system engineering requirements analysis, design and model management, simulations to validate requirements and analyze architecture, and code generation. Unsure which versions are used within NASA. Listed requirements are those related to these topics.)

IV&V GSFC ?

FishEye

COTS

Atlassian

https://www.atlassian.com/software/fisheye ...

Visualize and report on activity and search for commits, files, revisions, or teammates across SVN, Git, Mercurial, CVS and Perforce.

LaRC, GRC

EDK/ISE

COTS

Xilinex

http://www.xilinx.com/products/design-tools/ise-design-suite.html ...

Xilinx ISE (Integrated Software Environment) is a package that contains the suite of programs needed for the entire FPGA development flow. Includes design entry, synthesis, P&R, device programming. Also simulation via modelsim, as an option.

GSFC

Doxygen

Open Source

Open Source

http://www.stack.nl/~dimitri/doxygen/ ...

Doxygen is a tool for generating documentation from annotated C++ sources, but it also supports other popular programming languages such as C, Objective-C, C#, PHP, Java, Python, IDL (Corba, Microsoft, and UNO/OpenOffice flavors), Fortran, VHDL, Tcl, and to some extent D. Version 1.8.14 (release date December 25th 2017)

LaRC, GRC, JSC

Altium®

COTS

Altium Limited

http://www.altium.com/na/ ...

"Design the physical board, the programmable hardware on the board and the system software, all within a single design application. " Version "Designer 18"

DFRC, KSC

6. Lessons Learned

The NASA Lesson Learned database contains the following lessons learned related to software design:

  • Preliminary Design Review. Lesson Learned 0655: By not holding a PDR "one or a number of potential problems which could result in an adverse impact on the system, subsystem, and/or project might not be identified in a timely manner. This oversight might later result in a condition having a significant effect on quality, reliability, capability, schedule, and/or cost...Conduct a formal Preliminary Design Review (PDR) at the system and subsystem levels prior to the start of subsystem detail design, to assure that the proposed design and associated implementation approach will satisfy the system and subsystem functional requirements." 514
  • Critical Design Review for Unmanned Missions. Lesson Learned 0657: "In the absence of a CDR, potential problems with adverse impacts on the subsystem, system, or project may not be identified in a timely manner. This oversight may later result in a condition having a significant effect on quality, reliability, capability, schedule, or cost." 515
  • Lessons Learned From Flights of "Off the Shelf" Aviation Navigation Units on the Space Shuttle, GPS (Importance of Accurate Interface Control Document.) Lesson Learned 1370: "If the integrator and user do not have access to firmware and firmware requirements, the ICD may be the only written source of information on unit parameters. Developers of software that will interface with the unit must examine the ICD closely. .... An inaccurate ICD will lead to software and procedural issues that will have to be addressed before a system can be certified as operational. An accurate ICD is also needed for instrumentation port data that is critical during the test and verification phase of a project...Short development schedules may result in changes to the ICD while host vehicle software requirements are being defined and software is in development and test. A disciplined process of checks must be in place to ensure that the ICD and software requirements for units that interface with the [hardware and instruments] are consistent. Individuals who have knowledge of both [hardware] requirements and requirements for other interfacing units must be able to communicate and be involved in any changes made to the ICD." 551
  • MER Spirit Flash Memory Anomaly (2004). Lesson Learned 1483: "Shortly after the commencement of science activities on Mars, an MER rover lost the ability to execute any task that requested memory from the flight computer. The cause was incorrect configuration parameters in two operating system software modules that control the storage of files in system memory and flash memory. Seven recommendations cover enforcing design guidelines for COTS software, verifying assumptions about software behavior, maintaining a list of lower priority action items, testing flight software internal functions, creating a comprehensive suite of tests and automated analysis tools, providing downlinked data on system resources, and avoiding the problematic file system and complex directory structure." 557
  • NASA Study of Flight Software Complexity. Lesson Learned 2050: "Flight software development problems led NASA to study the factors that have led to the accelerating growth in flight software size and complexity. The March 2009 report on the NASA Study on Flight Software Complexity contains recommendations in the areas of systems engineering, software architecture, testing, and project management." 571