|
NASA Software Documentation Standard |
Software Engineering Program
NASA-STD-2100-91
Approved: July 29, 1991
National Aeronautics and
Space Administration
Washington, DC 20546
The NASA Software Documentation Standard (hereinafter referred to as "Standard") is designed to support the documentation of all software developed for NASA; its goal is to provide a framework and model for recording the essential information needed throughout the development life cycle and maintenance of a software system. The Standard will have been successfully applied if the project manager (NASA) has tailored it to a minimum set and if the resulting documentation meets the following criteria:
The organizational philosophy of the Standard is straightforward. There are four main volumes of produced documentation: the Management Plan; Product Specification; Assurance and Test Procedures; and Management, Engineering, and Assurance Reports. All project planning information, including management, engineering, and assurance planning, is documented in the Management Plan. All technical engineering information is recorded in the Product Specification. All technical assurance information is placed in the Assurance and Test Procedures. All reports are kept in the Management, Engineering, and Assurance Reports.
The Standard provides a top-level Data Item Description (DID) for a documentation set and a DID for each volume that consist of a table of contents (format) along with requirements for what is to be addressed in each section (content). If needed, the base table of contents can be given greater substructure through the use of additional DIDs. DIDs may be modified so that sections that are not applicable are marked N/A and not used, and additional needed sections are added through tailoring. Volumes may be produced either in the same top-level document or in separate documents.
The major sections of the Standard are as follows: Section 1.0 provides purpose, scope, and application of the Standard; Section 2.0 includes references, abbreviations, acronyms, and glossary. All requirements found in the Standard are contained in Section 3.0, with general requirements in Section 3.1, specific requirements for tailoring the Standard in Section 3.2, and requirements and rules for creating documentation based on the tailored Standard in Section 3.3. Section 4.0, Quality Assurance Provisions, addresses assurance and enforcement of the Standard. Section 5.0, Packaging, does not apply to the Standard and is therefore not applicable. Section 6.0 contains additional useful information, including explanations and examples. Appendix A contains a tailoring checklist consisting of a single outline, using all the Data Item Descriptions (DIDs). Appendix B contains the two master DIDs for creating documentation: the top-level DID whose four sections are the four volumes (Software Documentation Set DID) and a DID used for creating separate documents while maintaining traceability (Template DID). Appendices C, D, E, and F contain, respectively, the DIDs for the Management Plan; Product Specification; Assurance and Test Procedures; and Management, Engineering, and Assurance Reports.
1.0 SCOPE, PURPOSE, AND APPLICATION 1.1 SCOPE 1.2 PURPOSE 1.3 APPLICATION
2.0 REFERENCES 2.1 REFERENCED DOCUMENTS 2.2 ABBREVIATIONS AND ACRONYMS 2.3 GLOSSARY
3.0 REQUIREMENTS 3.1 IMPLEMENTATION REQUIREMENTS 3.2 TAILORING REQUIREMENTS 3.3 DOCUMENTATION REQUIREMENTS
4.0 QUALITY ASSURANCE PROVISIONS
6.0 ADDITIONAL INFORMATION 6.1 RELATIONSHIP BETWEEN ACQUIRER AND PROVIDER 6.2 DOCUMENT TITLES 6.3 TAILORING CHECKLIST APPENDIX A - DOCUMENTATION SET OUTLINE AND CHECKLIST
APPENDIX B - MASTER DOCUMENTATION DATA ITEM DESCRIPTIONS
NASA-DID-000 Software Documentation Set DID NASA-DID-999 Template DID
APPENDIX C - MANAGEMENT PLAN DATA ITEM DESCRIPTIONS
NASA-DID-M000 Management Plan DID NASA-DID-M100 Acquisition Activities Plan DID NASA-DID-M200 Development Activities Plan DID NASA-DID-M210 Training Development Plan DID NASA-DID-M300 Sustaining Engineering and Operations Activities Plan DID NASA-DID-M400 Assurance Plan DID NASA-DID-M500 Risk Management Plan DID NASA-DID-M600 Configuration Management Plan DID NASA-DID-M700 Delivery and Operational Transition Plan DID
APPENDIX D - PRODUCT SPECIFICATION DATA ITEM DESCRIPTIONS
NASA-DID-P000 Product Specification DID NASA-DID-P100 Concept DID NASA-DID-P200 Requirements DID NASA-DID-P300 Architectural Design DID NASA-DID-P400 Detailed Design DID NASA-DID-P410 Firmware Support Manual DID NASA-DID-P500 Version Description DID NASA-DID-P600 User's Guide DID NASA-DID-P700 Operational Procedures Manual DID
APPENDIX E - ASSURANCE AND TEST PROCEDURES DATA ITEM DESCRIPTIONS
NASA-DID-A000 Assurance and Test Procedures DID NASA-DID-A100 Assurance Procedures DID NASA-DID-A200 Test Procedures DID
APPENDIX F - MANAGEMENT, ENGINEERING, AND ASSURANCE REPORTS DATA ITEM DESCRIPTIONS
NASA-DID-R000 Management, Engineering, and Assurance Reports DID NASA-DID-R001 Certification Report NASA-DID-R002 Audit Report NASA-DID-R003 Inspection Report NASA-DID-R004 Discrepancy (NRCA) Report NASA-DID-R005 Engineering Change Proposal NASA-DID-R006 Lessons Learned Report F-10 NASA-DID-R007 Performance/Status Reports NASA-DID-R008 Assurance Activity Report NASA-DID-R009 Test Report NASA-DID-R010 Waiver/Deviation Request NASA-DID-R011 Review Report
The NASA Software Documentation Standard (hereinafter referred to as Standard) can be applied to the documentation of all NASA software. This Standard is limited to documentation format and content requirements. It does not mandate specific management, engineering, or assurance standards or techniques.
This Standard defines the format and content of documentation for software acquisition, development, and sustaining engineering. Format requirements address where information shall be recorded and content requirements address what information shall be recorded.
This Standard provides a framework to allow consistency of documentation across NASA and visibility into the completeness of project documentation. This basic framework consists of four major sections (or volumes). The Management Plan contains all planning and business aspects of a software project, including engineering and assurance planning. The Product Specification contains all technical engineering information, including software requirements and design. The Assurance and Test Procedures contains all technical assurance information, including Test, Quality Assurance (QA), and Verification and Validation (V&V). The Management, Engineering, and Assurance Reports is the library and/or listing of all project reports.
Selection and use of this Standard is the responsibility of program/project management and is to be determined on a program/project basis.
IEEE Standard Glossary of Software Engineering Terminology. ANSI/IEEE Standard 729-1983. New York: Institute of Electrical and Electronic Engineers, Inc.
Military Standard for Defense System Software Development, DoD-STD-2167, 4 June 1985, and DoD-STD-2167A, 27 October 1987.
NASA Software Management, Assurance, and Engineering Policy, NMI 2410.10, March 26, 1991.
For terms not appearing in this glossary, refer to the IEEE Standard Glossary (as referenced in Section 2.1).
Acceptance Review (AR) - The phase transition review for the Acceptance and Delivery life cycle phase.
Acquirer - An organization that obtains a capability, such as a software system.
Adaptation - The tailoring of the documentation standards (within the specifications of the rules and guidelines) for a specific program, project, or software system.
Assurance - Those activities, independent of the organization conducting the activity, that demonstrate the conformance of a product or process to a specified criteria (such as a design or a standard).
Assurance and Test Procedures - One of four logical volumes in a documentation set; it encompasses all the technical (i.e., nonplanning) aspects of the assurance activities.
Baselining - The official acceptance of a product or its placement under configuration management as defined in the Management Plan.
Certification - The process of confirming that a system, software subsystem, or computer program is capable of satisfying its specified requirements in an operational environment. Certification usually takes place in the field under actual conditions, and is used to evaluate not only the software itself, but also the specifications to which the software was constructed. Certification extends the process of verification and validation to an actual or simulated operational environment.
Computer Software Component (CSC) - A functional or logically distinct part of a computer software configuration item. Computer software components may be top-level or lower level.
Computer Software Configuration Item (CSCI) - A collection of software elements treated as a unit for the purpose of configuration management.
Computer Software Unit (CSU) - The smallest logical entity specified in the design of a computer software component and the actual physical entity in code that implements a testable aspect of the requirements. This is the smallest unit for which documentation may be required.
Critical Design Review (CDR) - The phase transition review for the Detailed Design life cycle phase.
Data Item Description (DID) - The table of contents and associated content description of a document or volume.
Developer - The provider organization responsible for development of software.
Document - A physically separate book in a documentation set.
Documentation Set - The four logical volumes for a software system. These volumes are the Management Plan; Product Specification; Assurance and Test Procedures; and Management, Engineering, and Assurance Reports.
Evolutionary Acquisition - The acquisition of software over a relatively long period of time in which two or more complete iterations of a life cycle will be employed to revise and extend the system to such an extent as to require a major requirements analysis and therefore subsequent life cycle iterations.
Firmware - Hardware that contains a computer program and data that cannot be changed in its user environment. The computer programs and data contained in the firmware are classified as software; the circuitry containing the computer program and data is classified as hardware.
Functional Configuration Audit (FCA) - The formal examination of functional characteristics' test data for a computer software configuration item, prior to acceptance, to verify that the item has achieved the performance specified in its functional or allocated configuration identification.
Hardware - Physical equipment used in data processing, as opposed to computer programs, procedures, rules, and associated documentation.
Increment - A predefined set of units integrated for integration testing by the development organization in response to incremental development plans.
Incremental Development - The process of developing a product before delivery in a series of segments. These segments remain internal to the development organization. The process is used to help minimize risk. The segments are defined based on the design and documented in the Design section of the Product Specification. The process leads to a single delivery unless used in conjunction with "phased delivery."
Independent Verification and Validation (IV&V) - Verification and validation performed by an organization independent of the development organization. For complete independence, the IV&V organization reports directly to and is funded directly by the acquirer.
Life Cycle (software) - The period of time that starts when a software product is conceived and ends when the software is no longer available for use. The software life cycle traditionally has eight phases: Concept and Initiation; Requirements; Architectural Design; Detailed Design; Implementation/Coordination; Integration and Test; Acceptance and Delivery; and Sustaining Engineering and Operations. This example is referred to as the waterfall life cycle.
Management, Engineering, and Assurance Reports - One of four logical volumes in the documentation set; it represents a "logical" home for all reports and request forms.
Management Plan - One of four logical volumes in a documentation set; it encompasses all planning information, including management, engineering, and assurance planning.
Metric - Quantitative measure of extent or degree to which software possesses and exhibits a certain characteristic, quality, property, or attribute.
Partitioning - The process of determining the content for each delivery when using the phased delivery approach, or for determining the content of each segment when using incremental development.
Phase - The period of time during the life of a project in which a related set of software engineering activities are performed. Phases may overlap.
Phase Transition Review - The review at the end of a phase triggering transition to the next phase.
Phased Delivery - The process of developing and delivering a product in stages, each providing an increasing capability for the software. The process may be employed to provide an early operational capability to users, for budgetary reasons, or because of risk, size, or complexity. Each delivery should undergo acceptance testing prior to release for operational use. The capabilities provided in each delivery are determined by prioritizing and partitioning the requirements. This is to be documented in the Requirements section of the Product Specification.
Physical Configuration Audit (PCA) - The formal examination of the "as-built" configuration of a unit of a computer software configuration item against its technical documentation in order to establish the computer software configuration item's initial product configuration identification.
Preliminary Design Review (PDR) - The phase transition review for the Architectural Design life cycle phase.
Product Specification - One of four logical volumes in a documentation set; it encompasses all the technical engineering information related to the development of the software.
Prototyping - A process used to explore alternatives and minimize risks. Prototyping can be used in any life cycle phase. The product of the process is usually a report.
Provider - An organization providing a capability to an acquirer; e.g., the developer or an organization providing IV&V.
Quality Assurance (QA) - A subset of the total assurance activities generally focused on conformance to standards and plans.
Quality Engineering - The process of incorporating reliability, maintainability, and other quality factors into software products.
Repository - A collection of standards, procedures, guides, practices, rules, etc., that supplements information contained in a documentation set. In general, the documentation set describes "what" is to be done and the repository provides the "how to" instructions. A repository usually contains information that is applicable to multiple software systems.
Requirements Allocation - The process of distributing requirements of a software system to subordinate software subsystems or lower level elements.
Requirements Partitioning - The process of distributing requirements of software to different deliveries in support of phased delivery.
Requirements Review (RR) - The phase transition review for the Requirements life cycle phase.
Review Item Discrepancy - A type of discrepancy report used when reviewing documentation.
Risk - The combined effect of the likelihood of an unfavorable occurrence and the potential impact of that occurrence.
Risk Management - The process of assessing potential risks and reducing those risks within budget, schedule, and other constraints.
Roll-out - A mechanism for recording sections of a volume in physically separate documents while maintaining traceability and links to the parent document.
Software - Programs, procedures, rules, and any associated documentation and data pertaining to the operation of a computer system, including programs and data contained in firmware.
Template DID - Framework used in the roll-out process for defining the specific format of a section rolled-out into a physically separate document.
Test Readiness Review (TRR) - The phase transition review for the Integration and Test life cycle phase.
Testing - The process of exercising or evaluating software by manual or automated means to demonstrate that it satisfies specified requirements or to identify differences between expected and actual results.
Tool - A hardware device or computer program used to help develop, test, analyze, or maintain another device or computer program or its documentation.
Unit - see Computer Software Unit.
Verification and Validation - The process of evaluating software to ensure compliance with requirements and determining whether or not the products of a given phase of development fulfill the requirements established during the previous phase.
Volume - One of the four basic types of information to be addressed for each software acquisition/development activity. The four volumes are the Management Plan; Product Specification; Assurance and Test Procedures; and Management, Engineering, and Assurance Reports.
This section contains all requirements for implementing the Standard, tailoring the DIDs, and producing the documentation. Section 3.1, Implementation Requirements, contains requirements for designing the overall structure of the project documentation. Section 3.2, Tailoring Requirements, contains requirements for tailoring the DIDs. Section 3.3, Documentation Requirements, contains content and structure requirements for producing documentation.
3.1.1 All delivered project documentation shall be produced in accordance with this Standard.
3.1.2 The project manager shall develop a documentation tree, or trees, as dictated by the structure of the project.
3.1.3 Each documentation tree shall address all four major sections (or volumes) of the Standard.
3.1.4 The documentation tree shall contain at least one instance of each of these volumes.
3.1.5 This documentation tree (text or graphic) shall be placed in Section 1.5, Documentation Organization, of each document belonging to the tree.
3.1.6 The creation of documentation shall be accomplished by using the DIDs (as tailored) contained in Appendices B through F of this Standard.
3.1.7 For development and/or acquisitions of software having the highest classification (per NMI 2410.10), Sections 5.0 and 6.0 of the Acquisition Activities Plan section of the Management Plan shall be completed without tailoring.
A certain amount of tailoring is expected on every software acquisition or development project. The main purpose of tailoring is to achieve a balance between software documentation needs and cost. The project manager should not apply a requirement or ask for a piece of documentation if it is not needed for the project's success. The project manager should consider the special risks, needs, and limitations of a specific software project, and then tailor the DIDs accordingly.
Tailoring of this Standard consists of the following: a) evaluating individual sections of the DIDs to determine the extent to which the documentation called for is needed in a specific application; and b) modifying the DIDs by adding new sections, identifying sections that are not applicable (N/A), or changing text within sections in order to clarify the intent of that section.
The complete table of contents for a documentation set is included in Appendix A. This table of contents can serve as a detailed tailoring checklist.
3.2.1 The project manager, in conjunction with the product assurance manager, shall tailor the DIDs to a specific software acquisition or development activity before levying this Standard on that activity.
3.2.2 For all documentation, the project manager shall determine which sections and subsections are applicable, and each section and subsection determined to be not applicable to the project shall be marked "N/A."
3.2.3 If all subsections of a given section are not applicable or if the information expected from these subsections can be provided in a short unfragmented form, then the subsections shall be removed from the tailored standard, while keeping the section.
3.2.4 When information is desired, but no logical subsection exists in the original DID, the project manager shall add new subsections to the DID at the end of the appropriate section, after all original subsections.
3.2.5 When any subsections are used within a section, all other original subsections shall be listed, even if they are marked N/A.
3.2.6 The project manager shall modify the text in a subsection if that is needed for clarity or completeness without any change to intended purpose of the section.
The DIDs describe the format and contents for each section of the documentation set. Additionally, some sections of a DID specify the use of a lower level DID to prepare that particular section. This lower level DID contains the subsections and their format and content descriptions.
3.3.1 Project documentation shall be created using the DIDs, as tailored by the project manager, without reordering or renumbering.
3.3.2 All documents shall follow the section numbering and content description found in the tailored DIDs.
3.3.3 Each section and subsection shall contain one of six entries:
3.3.4 If a particular class of document (for example, Test Procedures) is to be produced in a format different from that given in the DIDs, the project manager shall produce a detailed mapping that indicates precisely where each piece of information called for in the DIDs may be found. This mapping shall then be included once in Section 1.5, Documentation Organization, of the Management Plan.
3.3.5 All new sections created shall only contain information that cannot appropriately be placed anywhere else in the tailored DIDs.
3.3.6 Each document shall contain a list (in the form of a table of contents) in Section 1.5, Documentation Organization, that shows which sections and subsections have been:
NOTE: Appendix A contains a complete Table of Contents for a documentation set.
3.3.7 All documents shall contain the DID number of the highest level DID used to produce that document. This number should be placed either on the cover or in the Applicable Documents Section.
3.3.8 Roll-out
Roll-out is a mechanism for recording sections of one document in physically separate documents while maintaining traceability. Roll-out is to be used if the project manager needs to break up a document into multiple documents.
Some factors influencing a decision in favor of roll-out include:
3.3.8.1 A rolled-out document shall include every section and subsection contents and format from the point exited from its parent document.
3.3.8.2 A rolled-out document shall contain introductory and supplemental sections specified in DID-999 Template DID.
3.3.8.3 Each rolled-out document shall be titled as illustrated below. This method supports the Standard and enables the document to be placed in context with its parent document(s).
Note that the document entry in brackets ([]) is to be expanded zero or more times depending on the number of levels of roll-out from the documentation set parent. Additional information may be included on the title page as specified by delivery requirements.
The program/project manager is responsible for assuring and enforcing this Standard in the following ways:
It is the responsibility of any reviewer to be familiar with the particular aspects of this Standard that are applicable to the products or processes under review and to question any deviations. In particular, a reviewer should ensure:
The detailed outline and contents specifications for documentation can be used by reviewers as a gross level checklist.
Not Applicable. There are no packaging requirements associated with this Standard.
THIS SECTION CONTAINS NO REQUIREMENTS.
This section provides additional information and examples for certain elements of the Standard. The examples are given as the most likely interpretation of the requirements given in the Standard, but are not exclusive.
The Standard defines two types of organizations, acquirers and providers. The acquirer is the organization that is purchasing the software, product, or associated service. In most cases, the acquirer is NASA or an organization within NASA. The provider is the organization that is delivering that product or service. This can be a contractor, a separate NASA organization, or, in some cases, the acquirer and provider are the same organization. A provider may provide software, IV&V, subcontractor support, consulting, etc. A provider is ultimately responsible for providing something to the acquirer in accordance with the acquirer's requirements.
If the acquirer of a software system is NASA and the provider is a contractor, a typical scenario of how the acquirer and provider documents would be produced is as follows. The acquirer determines that a software system is needed, and creates a Management Plan (in particular, an Acquisition Plan) for that software. The acquirer then creates an RFP and SOW based on this plan. The provider winning the contract will produce a Management Plan based on the SOW, and a Product Specification, Assurance and Test Procedures, and Management, Engineering, and Assurance Reports based on that Management Plan. The acquirer will continue documentation in its Management Plan, and will create Assurance and Test Procedures and Management, Engineering, and Assurance Reports for the acquirer's activities.
The following is an example of a cover page for a document when complying with requirements 3.3.7 and 3.3.8.3. Assuming that this is a rolled-out Acquisition Activities Plan section of a Management Plan, the cover would contain the following information:
ACQUISITION ACTIVITIES PLAN of the MANAGEMENT PLAN of the XYZ SOFTWARE SYSTEM
The DID number in the lower left-hand corner is the DID number of the highest level DID used to produce this document; in this case, NASA-DID-M100, Acquisition Activities Plan.
Appendix A contains a detailed outline (in the form of a table of contents) of every section and subsection comprising the Management Plan; Product Specification; Assurance and Test Procedures; and the Management, Engineering, and Assurance Reports. This list may be a useful aid to the person tailoring the Standard. To use the list, simply go down the list and check off every section and subsection as applicable or nonapplicable. Once this is done, go through the list again and check off any sections that will contain pointers, either due to roll-out or because the information is found somewhere else. Once this is completed, this list is placed in Section 1.5, Documentation Organization, of each document produced in order to satisfy requirement 3.3.6.
If you have any questions or comments about the SATC, contact:
Dr. Linda Rosenberg
NASA/GSFC
Code 302 - Bldg 6
Greenbelt, MD 20771
Linda.Rosenberg@gsfc.nasa.gov
This page was last updated on:
06/29/99