Return to 7.18 - Documentation Guidance
- 1. Minimum Recommended Content
- 2. Rationale
- 3. Guidance
- 4. Small Projects
- 5. Resources
- 6. Lessons Learned
1. Minimum Recommended Content
- Project organizational structure showing authority and responsibility of each organizational unit, including external organizations (e.g., Safety and Mission Assurance, Independent Verification and Validation (IV&V), Technical Authority, NASA Engineering and Safety Center, NASA Safety Center).
- The safety criticality and classification of each of the systems and subsystems containing software.
- Tailoring compliance matrix for approval by the designated Engineering Technical Authority, if the project has any waivers or deviations to this NPR.
- Engineering environment (for development, operation, or maintenance, as applicable), including test environment, library, equipment, facilities, standards, procedures, and tools.
- Work breakdown structure of the life-cycle processes and activities, including the software products, software services, non-deliverable items to be performed, budgets, staffing, acquisition approach, physical resources, software size, and schedules associated with the tasks.
- Management of the quality characteristics of the software products or services.
- Management of safety, security, privacy, and other critical requirements of the software products or services.
- Subcontractor management, including subcontractor selection and involvement between the subcontractor and the acquirer, if any.
Identification of selected software verification methods and criteria across the life cycle (e.g., software peer review/inspections procedures, re-review/inspection criteria, testing procedures).
Identification of selected work products to be verified.
Description of software verification environments that are to be established for the project (e.g., software testing environment, system testing environment, regression testing environment).
Identification of where actual software verification records and analysis of the results will be documented (e.g., test records, software peer review/inspection records) and where software verification corrective action will be documented.
Identification of selected software validation methods and criteria across the life cycle (e.g., prototyping, user groups, simulation, analysis, acceptance testing, operational demonstrations).
Identification of selected work products to be validated.
Description of software validation environments that are to be established for the project (e.g., simulators for operational environment).
Identification of where actual software validation records and analysis of the results will be documented (e.g., user group records, prototyping records, and acceptance testing records) and where software validation corrective action will be documented.
- Acquirer involvement.
- User involvement.
- Risk management.
- Security policy.
- Approval required by such means as regulations, required certifications, proprietary, usage, ownership, warranty, and licensing rights.
- Process for scheduling, tracking, and reporting.
- Training of personnel, including project unique software training needs.
- Software life-cycle model, including description of software integration and hardware/software integration processes, software delivery, and maintenance.
- Configuration management.
- Software documentation tree.
- Software peer review/inspection process of software work products.
- Process for early identification of testing requirements that drive software design decisions (e.g., special system level timing requirements/checkpoint restart).
- Software metrics.
- Content of software documentation to be developed on the project.
- Management, development, and testing approach for handling any commercial-off-the-shelf (COTS), government-off-the-shelf (GOTS), modified-off-the-shelf (MOTS), reused, or open source software component(s) that are included within a NASA system or subsystem.
Software development requires thought and planning before implementation. It is important to document, review, and approve the activities, tools, responsibilities, and other tasks needed to develop software before beginning the work. Planning helps the team consider and put in place those elements needed to efficiently produce the software in the allotted time frame and within the allotted budget. The plan also provides a basis for monitoring the project's adherence to these processes.
Planning allows others within the project and external to the project to evaluate, integrate, and critique the proposed approach, and the resulting plan helps new members of the software team get up to speed when joining the project. Planning also allows a current project to consider lessons learned from previous projects to avoid previously experienced difficulties.
The Software Development or Management Plan provides insight into, and a tool for monitoring, the processes to be followed for software development, the methods to be used, the approach to be followed for each activity, and project schedules, organization, and resources. This plan details the system software, project documentation, project schedules, resources requirements and constraints, and general and detailed software development activities.
Begin writing the plan as soon as any information about the project definition and scope becomes available. Complete the plan by the end of the requirements analysis phase, except for information available only at later phases, e.g., the build plan is typically inserted during the design phase. If items in the Software Development or Management Plan (SDP or SMP) are missing for any reason, the manager indicates who will supply the information and when it will be supplied. 031 It is important to keep the plan up to date throughout the project life cycle. Refer to Topic 7.8 - Maturity of Life-Cycle Products at Milestone Reviews for expected plan maturity and updates at various life-cycle milestones.
The following roles may be involved in creating the SDP/SMP:
- Software Lead Engineer.
- Test Team Lead. 453
- Software Engineers.
- Software Assurance Engineer (to coordinate assurance activities and schedule).
- Software Acquisition personnel.
- Software Configuration Management Engineer.
- System Engineer.
The content of the SDP/SMP is the recommended minimum content; additional content may be included as appropriate for the project. This content may be entirely captured in the SDP/SMP, or it may be captured in the SDP/SMP and some number of other plans. When other plans capture any of the recommended SDP/SMP content, reference those plans in the SDP/SMP.
When developing an SDP/SMP, consider the following guidance for each of the minimum recommended elements of the plan:
Project organizational structure
Describe in text, graphics, or both the authority and responsibility of each unit of the organization having a role in the development of the software. Include both internal and external organizations relevant to the software development effort:
- Software Engineering.
- Organizational support, such as configuration management, verification and validation (V&V), training, metrics, process development.
- Hardware development and manufacturing.
- System Engineering.
- Safety and Mission Assurance.
- Independent Verification and Validation (IV&V).
- Software/Engineering Technical Authority.
- NASA Engineering and Safety Center.
- NASA Safety Center.
Safety criticality and classification of each of the systems and subsystems containing software
Capture the results of software classification (SWE-020) and safety-criticality (SWE-133) determination of the project systems and subsystems containing software. This information may change as the project proceeds through its life cycle and the team is responsible for keeping this part of the SDP/SMP current with those changes.
Tailoring compliance matrix
The tailoring compliance matrix shows how the project will comply with NPR 7150.2 (see SWE-125). If the project has any waivers or deviations to NPR 7150.2, include a table showing the NPR 7150.2 requirements the project plans to meet, those waived by the project, and those from which the project plans to deviate. For waivers and deviations, follow the appropriate approval processes, and record in the table those waivers and deviations approved for the project. Until those approvals are received, the table represents the planned compliance for the project.
The matrix is reviewed and approved by the appropriate Engineering Technical Authority or Center-designated authority for review of tailoring.
Engineering environment (for development, operation, or maintenance, as applicable)
Describe "the methods, tools, and techniques to be used to specify, design, build, test, integrate, document, deliver, modify, and maintain the software products". 057
Include information such as:
- Development methodologies.
- Programming languages.
- Technical standards.
- Development and test tools.
- Coding standards.
- Operating systems.
- Equipment such as simulators or specialized testbeds.
- Facilities, including any physical security needs.
- Policies and procedures.
Work breakdown structure (WBS) of the life-cycle processes and activities
The WBS describes the work activities and the relationships (order, dependencies, etc.) among those activities. Decompose the WBS to a level that allows "accurate estimation of resource requirements and schedule duration for each work activity." 057
Include in the WBS the software products and non-deliverable items to be created; the software services to be performed; budgets, staffing, acquisition approach, physical resources, software size, and schedules associated with the tasks.
If appropriate or desired, a complete schedule and a staffing plan may be provided in their own sections of the SDP/SMP or in separate documents with references included in the SDP/SMP.
Management of the quality characteristics of the software products or services
Describe how the quality characteristics (e.g., availability, reliability, usability, maintainability, portability, performance, correctness) of the software products and services will be managed for the software development life cycle. Include the processes for measuring, tracking, reporting, and determining if the software meets the required levels of these characteristics, as specified in the software requirements. If addressed in a separate document, reference that plan in the SDP/SMP.
Management of safety, security, privacy, and other critical requirements of the software products or services
Describe how the safety, security, privacy, and other critical requirements of the software products and services will be managed for the software development life cycle, including information security, controlled data access, and other information management aspects of the software functionality. If addressed in a separate software assurance plan, reference that plan in the SDP/SMP. Possible items to include are:
- Assessment of the sensitive information that is to be managed and controlled by the software. 145
- Development, validation, verification, and management of security, privacy, and safety requirements. 145
- Identification of safety-critical requirements.
- Compliance with NASA-STD-8719.13, Software Safety Standard. 271
- Compliance with NPD 2810.1, NASA Information Security Policy 402, as applicable.
- Compliance with NPR 2810.1, Security of Information Technology 403, as applicable.
See the Security Policy section below for additional, related information.
Describe subcontractor selection and involvement between the subcontractor and the acquirer, if any. If subcontractor selection, including the process, personnel, and criteria used, is described in a procurement plan, reference that document here.
Involvement between the subcontractor and acquirer includes but is not limited to any or all of the following:
- On-site audits of subcontractor processes and products.
- Meetings and decision points that occur during the software development life cycle.
- Formal, progress, and technical reviews.
- Progress reports and deliverables.
See Topic 7.3 - Acquisition Guidance and SWE-039 through SWE-043 and SWE-045 through SWE-047 for additional information on subcontractor management tasks and interactions between the subcontractor (provider) and acquirer, particularly those that need to be included in contracts and which need to be managed once the contract has been awarded.
Verification and validation
Describe the planned activities for verification (see SWE-028) and validation (see SWE-029) or provide an introduction/overview and reference the appropriate documentation (e.g., verification and validation plan, test plan) where those process and activity descriptions are captured.
Verification and validation planning results in the tasks to be performed; the resources needed; as well as the specification of techniques, methods and procedures, as well as automated tools to be used to carry out these tasks. 057
Describe how the acquirer will be involved in any software development performed by an organization external to the acquirer (e.g., another NASA organization, subcontractor), including activities such as but not limited to:
- Conducting or attending reviews.
- Conducting or reviewing the results of audits.
- Attending informal meetings.
- Receipt and/or review of reports.
- Review and/or approval of modifications and changes.
- Involvement in implementation tasks.
- Acceptance of the product. 224
Include in this section any access to facilities needed by the acquirer for their involvement in the software life cycle. 224
Describe how the user will be involved in the software life cycle, including activities such as requirements development, prototype demonstrations, and software evaluations. 224 Items to consider capturing include scheduling, level of participation, expected inputs, expected results, and/or which specific user groups will be involved in each activity. Additionally, capture any expected or planned items to be supplied by the user, such as operational scenarios, a piece of software, a test facility, or a piece of hardware into which the software will be integrated.
Describe how risk management will be performed on this software project, or reference a separate risk management plan (see SWE-086 ). The risk management plan addresses initial risks and mitigation approaches for them, 453 as well as the plan for identifying and mitigating new risks as the software development progresses. Risk management also includes the risk strategy, such as the criteria or process by which risks get raised to the mission level or determining which risks need mitigation plans.
Describe "the rules for need-to-know and access-to-information at each project organization level." 224Include the processes for ensuring the control and protection of the software being developed, associated support tools, and data. 145 Include the plans for physical security of facilities. As applicable, include compliance with NPD 2810.1 402 and with NPR 2810.1 403.
Describe approvals required by the project for acceptance, operation, and maintenance activities, including regulatory approvals, required certifications, proprietary, usage, ownership, warranty, and licensing rights.
Process for scheduling, tracking, and reporting
Describe how task scheduling, progress tracking, and reporting will be performed for this project. Include information such as:
- The "plan for tracking the progress and cost of the individual work elements in each WBS category using an approved method." 453
- A description of the use of Earned Value (EV) or similar technique, as applicable.
- A description of the lowest WBS where progress reporting will be performed and how those low-level progress values will be rolled up and reported. 453
- "Methods, tools, techniques used to estimate and periodically re-estimate project cost, schedule, and resource requirements." 057
- Basis of estimation. 057
- Triggers for re-estimation. 057
- Types of reports and frequency of reporting (to Mission project, Branch, division, etc.).
Training of personnel
Describe the plans for training software personnel, including project-unique software training needs such as mission-specific training or training for knowledge, skills, and tools used only on this project. The training plan may be included in the SDP/SMP or in a separate plan. When developing the training plan, be sure to address:
- Type of training to be provided.
- When training will be provided, e.g., just before a particular life-cycle phase or a specific task.
- Personnel to receive specific types of training by role.
- Process for capturing, maintaining, and storing training records.
Refer to the Center Training Plan in this topic for opportunities that may meet some of the project's training needs.
Software life-cycle model
Provide a description of the planned life-cycle model chosen for the project (see SWE-019), making sure to address:
- Life-cycle phases and transition from one to the next.
- Life-cycle reviews.
- Milestones to be achieved.
- Baselines to be established.
- Required approvals.
- The software integration and hardware/software integration processes.
- Software delivery processes.
- Software operations and maintenance processes.
Describe how configuration management will be performed for the software, or reference a separate Software Configuration Management Plan (see SWE-079 and the Software Configuration Management Plan section of this topic for recommended minimum content). The Software Configuration Management Plan includes information such as:
- The build or release plan, including the number of planned builds. 453
- Identification of configuration items.
- Description of the configuration management system.
- The process for baselining work products. 057
- Processing change requests.
- Change control board activities.
- Status accounting.
- Communication of configuration management decisions and action, e.g., to appropriate stakeholders.
- Data management, if not captured elsewhere.
Software documentation tree
Describe the documents to be created as part of the project, the relationships among those documents, and the role or organization responsible for each document. The documentation tree may be graphical (e.g., a chart or tree diagram, textual, or both) to convey the relationships and document descriptions in the best manner possible to those who will need to understand it.
Software peer review/inspection process of software work products
Describe or provide an overview of the peer review and/or inspection process to be used for products created as part of the software development life cycle, e.g., plans, requirements, design, code. Specify which types of products will be reviewed, and if all code will not be reviewed, specify how code to be inspected is determined. Reference the appropriate project peer review/inspection processes and procedures (see SWE-087, SWE-088, and SWE-089). If the peer review/inspection process is documented in a separate document(s), provide an overview followed by a reference to the appropriate document(s).
Process for early identification of testing requirements that drive software design decisions
Describe how testing requirements that drive design decisions (e.g., special system-level timing requirements/checkpoint restart) will be identified and captured in the earliest phases of the life cycle, before costly design decisions are made that will need to be altered or replaced to accommodate testing requirements.
Describe any test requirements that drive or require early builds/deliveries to conduct tests on other system components. For example, an early software build is often required to enable early testing of some hardware capabilities.
Describe or provide an overview of the planned software measures to be collected, analyzed, and the metrics to be used for tracking and reporting progress, improving processes, identifying issues, and other purposes. Include collection and analysis procedures for the project. Define the project objectives for collecting the measures. Include references for any project processes and procedures that further describe or provide details for software metrics collection and processing (see SWE-091). Include, for each identified measure and metric:
- Collection method and frequency.
- Role responsible for collecting the data.
- Storage location and data retention.
- Analysis method and frequency.
- Analysis reporting method, frequency, and audience.
- Threshold that, if crossed, would prompt further analysis or other action.
Content of software documentation to be developed on the project
Provide content lists for the documents to be created as part of the project or a list of templates or standards governing and describing that content. This topic in the Handbook provides recommended content lists for several software documents. The content lists need not be incorporated in the SDP/SMP; they may be included by reference.
*Management, development, and testing approach for COTS (Commercial Off the Shelf), GOTS (Government Off the Shelf), MOTS (Modified Off the Shelf) , reused, open-source software component(s) that are included within a NASA system or subsystem*
Describe or reference processes specific to development, management, and testing of COTS, GOTS, MOTS, reused, or open-source software for this project. By their nature, these types of software present challenges because access may be limited to requirements, design, and testing documentation. Additionally, software stability, access and inclusion of updates and upgrades, and access to persons with critical knowledge of the software can present challenges not found in new software development.
Guidance for SWE-027 in this Handbook also describes special considerations relative to these types of software and their inclusion in NASA projects.
Include plans for dealing with these challenges and considerations in the SDP/SMP, or include references to the project documents that address them.
Other possible content
Other information that might be included, or referenced if captured elsewhere, in a SDP/SMP includes but is not limited to:
- Software deliverables. 453
- External dependencies affecting schedule and budget. 453
- Development method, such as structured programming or object-oriented programming. 453
- Prototyping, modeling, or simulation activities. 453
- Software assurance activities. 453
- Schedule. 453
- Effort. 453
- Budget. 453
- Data management, including project data, records, and information to be captured and maintained. 453
- Stakeholder involvement. 453
- Assumptions, e.g., planning and estimation assumptions. 453
- Issue handling for entities outside the control of the project, including escalation/appeal process. 057
- Staffing levels across the life cycle.
- User training.
Review at regular intervals, revise, and update the SDP/SMP to keep its content current "following significant changes in customer-specified requirements, budget, schedule, or other constraints. Criteria that often trigger re-planning include:
- Significant changes in scope, schedule, or budget.
- Delay in receipt of key component or service that is externally supplied.
- Inability to meet a major milestone." 453
Topic 7.8 - Maturity of Life-Cycle Products at Milestone Reviews provides guidance for the maturity of plans, including the SDP/SMP, at various life-cycle reviews.
Additional guidance related to software plans may be found in the following requirement in this Handbook:
4. Small Projects
SDPs/SMPs are required for every project because they provide the overall view of the development and management effort. However, plans are written to a level of detail appropriate for and commensurate with the size, complexity, risk, and required safety of the software. Small projects may wish to work with the Engineering Technical Authority to tailor an existing SDP/SMP specifically for small projects. Tailoring a proven plan from a similar project can reduce the overall plan development effort. Another option for small projects is to use one generic SDP/SMP to cover several small projects if they are managed in a similar fashion.When writing the SDP/SMP, small projects may choose to incorporate other plans, such as the software assurance plan or the configuration management plan, in the SDP/SMP. This means that project roles responsible for those plans may be part of the group authoring of the SDP/SMP.
(SWEREF-001) Software Development Process Description Document, EI32-OI-001, Revision R, Flight and Ground Software Division, Marshall Space Flight Center (MSFC), 2010.This NASA-specific information and resource is available in Software Processes Across NASA (SPAN), accessible to NASA-users from the SPAN tab in this Handbook.
(SWEREF-057) Software Management Plan (SMP) Template, GRC-SW-TPLT-SMP, NASA Glenn Research Center (GRC), 2009. This NASA-specific information and resource is available in Software Processes Across NASA (SPAN), accessible to NASA users from the SPAN tab in this Handbook.
(SWEREF-453) Project Planning Process, 580-PC-004-05, Software Engineering Division (ISD), NASA Goddard Space Flight Center (GSFC), 2014.This NASA-specific information and resource is available in Software Processes Across NASA (SPAN), accessible to NASA-users from the SPAN tab in this Handbook. Replaces SWEREF-088
(SWEREF-552)Kennedy Space Center (KSC) Projects and Resources Online (KPRO) Software Development and ImplementationPublic Lessons Learned Entry: 1384.
No tools have been currently identified for this Topic. If you wish to suggest a tool, please contact the Page Editor listed at the bottom of the page.
6. Lessons Learned
- Computer Hardware-Software/International Space Station/Software Development (Plan for user involvement). Lesson Learned 1132: "The lack of user involvement results in increased schedule and safety risk to the program... follow a concurrent engineering approach to building software that involves users and other key discipline specialists early in the software development process to provide a full range of perspectives and improve the understanding of requirements before code is developed." 542
- Computer Software/Software Safety Policy Requirements/Potential Inadequacies (Cover essential requirements for the project). Lesson Learned 1021: "NASA is committed to assuring that required program management plans and any subordinate plans such as software or safety management plans cover the essential requirements for programs where warranted by cost, size, complexity, lifespan, risk, and consequence of failure." 532
- Kennedy Space Center (KSC) Projects and Resources Online (KPRO) Software Development and Implementation (Project team planning). Lesson Learned 1384: "When planning and selecting team resources for a project, consider how the resources can work together and support each other, along with the skills required. This can be a factor in meeting or delaying software project milestones if an alternative resource has not been endorsed by the team members." 552