SOFTWARE ENGINEERING LABORATORY SERIES
SEL-81-305
Recommended Approach to Software Development
Revision 3
JUNE 1992
IVI/VSA
National Aeronautics and Space Administration
Goddard Space Flight Center
Greenbelt, Maryland 20771
C=:
■ I I
J II
1 "III
•IF I nil
■I "
FOREWORD
The Software Engineering Laboratory (SEL) is an organization sponsored by the National Aeronautics and Space Administration/Goddard Space Flight Center (NASA/GSFC) and created to investigate the effectiveness of software engineering technologies when applied to the development of applications software. The SEL was created in 1976 and has three primary organizational members:
NASA/GSFC, Software Engineering Branch
University of Maryland, Department of Computer Science
Computer Sciences Corporation, Software Engineering Operation
The goals of the SEL are (1) to understand the software development process in the GSFC environment; (2) to measure the effects of various methodologies, tools, and models on this process; and (3) to identify and then to apply successful development practices. The activities, findings, and recommendations of the SEL are recorded in the Software Engineering Laboratory Series, a continuing series of reports that includes this document.
The previous version of the Recommended Approach to Software Development was published in April 1983. This new edition contains updated material and constitutes a major revision to the 1983 version. The following are primary contributors to the current edition:
Linda Landis, Computer Sciences Corporation
Sharon Waligora, Computer Sciences Corporation
Frank McGarry, Goddard Space Flight Center
Rose Pajerski, Goddard Space Flight Center
Mike Stark, Goddard Space Flight Center
Kevin Orlin Johnson, Computer Sciences Corporation
Donna Cover, Computer Sciences Corporation
Single copies of this document can be obtained by writing to
Software Engineering Branch Code 552
Goddard Space Flight Center Greenbelt, Maryland 20771
iu
PRECEDING PAGE K'-AHX NOT FILMED
ACKNOWLEDGMENTS
In preparation for the publication of this document and the Manager's Handbook for Software Development, teams of technical managers from NASA/GSFC and Computer Sciences Corporation (CSC) met weekly for many months to resolve issues related to flight dynamics software development. It was through their efforts, experience, and ideas that this edition was made possible.
NASA/GSFC Team Members CSC Team Members
Sally Godfrey Linda Esker
Scott Green Jean Liu
Charlie Newman Bailey Spence
Rose Pajerski Sharon Waligora
Mike Stark Linda Landis Jon Valett
IV
ABSTRACT
This document presents guidelines for an organized, disciplined approach to software development that is based on studies conducted by the Software Engineering Laboratory (SEL) since 1976. It describes methods and practices for each phase of a software development life cycle that starts with requirements definition and ends with acceptance testing. For each defined life cycle phase, this document presents guidelines for the development process and its management, and for the products produced and their reviews.
This document is a major revision of SEL-8 1-205.
NOTE: The material presented in this document is consistent with major NAS A/GSFC standards.
NOTE: The names of some commercially available products cited in this document may be copyrighted or
registered as trademarks. No citation in excess of fair use, express or implied, is made in this document and none should be construed.
VI
CONTENTS
Section 1 — Introduction 1
Section 2 — The Software Development Life Cycle 5
Section 3 — The Requirements Definition Phase 21
Section 4 — The Requirements Analysis Phase 41
Section 5 — The Preliminary Design Phase 63
Section 6 — The Detailed Design Phase 85
Section 7 — The Implementation Phase 107
Section 8 — The System Testing Phase 135
Section 9 — The Acceptance Testing Phase , 161
Section 10 — Keys to Success 179
Acronyms 185
References ,...., 1 87
Standard Bibliography of SEL Literature 1 89
Index '. 201
vu
LIST OF FIGURES
Figure Page
1 - 1 The SEL Software Engineering Environment 1
2- 1 Activities by Percentage of Total Development Staff Effort 6
2-2 Reuse Activities Within the Life Cycle 1 6 2-3 Graph Showing in Which Life-Cycle Phases Each Measure
Is Collected 19
3-1 Generating the System and Operations Concept 23
3-2 Developing Requirements and Specifications 24
3-3 SOC Document Contents 33
34 Requirements and Specifications Document Contents 34
3-5 SCR Format 35
3-6 SCR Hardcopy Material Contents 36
3-7 SRR Format 37
3-8 SRR Hardcopy Material Contents 38
4-1 Analyzing Requirements 43
4-2 Timeline of Key Activities in the Requirements Analysis Phase 46
4-3 Effort Data Example - ERBS AGSS 53
4-4 Requirements Analysis Report Contents 55
4-5 SDMP Contents (2 parts) 56
4-6 SSR Format 59
4-7 SSR Hardcopy Material 60
5-1 Developing the Preliminary Design 65
5-2 Preliminary Design Phase Timeline 67 5-3 Extent of the Design Produced for FORTRAN Systems
During the Preliminary and Detailed Design Phases 72 5-4 Level of Detail Produced for Ada Systems During
Preliminary Design 73
5-5 Preliminary Design Report Contents 81
5-6 PDR Format 82
5-7 PDR Hardcopy Material 83
6-1 Generating the Detailed Design 87
6-2 Timeline of Key Activities in the Detailed Design Phase 88
6-3 Checklist for a Unit Design Inspection 94 64 Example of the Impact of Requirements Changes
on Size Estimates - the UARS Attitude Ground
Support System 98
6-5 Detailed Design Document Contents 100
6-6 CDR Format 103
6-7 CDR Hardcopy Material 104
7-1 Implementing a Software Build 109 7-2 Phases of the Life Cycle Are Repeated for
Multiple Builds and Releases 110
V1I1
LIST OF FIGURES (cont.)
Figure Pa8e
7-3 Timeline of Key Activities in the Implementation Phase 112
14 Sample Checklist for Code Inspection 1 1 8
7-5 Integration Testing Techniques 121
7-6 Development Profile Example 126
7-7 Example of CPU Usage -ERBSAGSS 128
7-8 Generalized Test Plan Format and Contents 131
7-9 BDR Format I33
7-10 BDR Materials 134
8-1 System Testing 136
8-2 Timeline of Key Activities in the System Testing Phase 138
8-3 Sample Software Failure Report Form 148
8^4 EUVEDSIM System Test Profile 152
8-5 SEL Discrepancy Status Model 152
8-6 User's Guide Contents 154
8-7 System Description Contents 156
8-8 ATRR Format 158
8-8 ATRR Materials 158
9-1 Acceptance Testing 163
9-2 Timeline of Key Activities in the Acceptance Testing Phase 1 64
9-3 Sample Error-Rate Profile, UARS AGSS 175
9-4 Software Development History Contents 178
LIST OF TABLES
Table Pa8e
2-1 Measures Recommended by the SEL 1 8
3-1 Objective Measures Collected During the Requirements Definition Phase 3 1
4- 1 Objective Measures Collected During the Requirements Analysis Phase 5 1
5-1 Objective Measures Collected During the Preliminary Design Phase 78
6- 1 Objective Measures Collected During the Detailed Design Phase 97
7-1 Objective Measures Collected During the Implementation Phase 125
8-1 Objective Measures Collected During the System Testing Phase 151
9-1 Objective Measures Collected During the Acceptance Testing Phase 174
IX
im mi ml
-ill mill
.III I
JIN
Jill 1
/lilfl I
.in
.jm III
n mil
mini
Jill If Ml
ill 1 1 II
■ III!
* I II
■ r
Section 1 - Introduction
SECTION 1
INTRODUCTION
This document presents a set of guidelines that constitute a disciplined approach to software development. It is intended primarily for managers of software development efforts and for the technical personnel (software engineers, analysts, and programmers) who are responsible for implementing the recommended procedures. This document is neither a manual on applying the technologies described here nor a tutorial on monitoring a govern- ment contract. Instead, it describes the methodologies and tools that the Software Engineering Laboratory (SEL) recommends for use in each life cycle phase to produce manageable, reliable, cost-effective software.
THE FLIGHT DYNAMICS ENVIRONMENT
The guidelines included here are those that have proved effective in the experiences of the SEL (Reference 1). The SEL monitors and studies software developed in support of flight dynamics applications at the National Aeronautics and Space Administration/Goddard Space Flight Center (NASA/GSFC). Since its formation in 1976, the SEL has collected data from more than 100 software development projects. Typical projects range in size from approximately 35,000 to 300,000 delivered source lines of code (SLOC) and require from 3 to 60 staff-years to produce.
Flight dynamics software is developed in two distinct computing environments: the Flight Dynamics Facility (FDF) and the Systems Technology Laboratory (STL). (See Figure 1-1.) Mission support software is engineered and operated in the mainframe environment of the FDF. This software is used in orbit determination, orbit adjustment, attitude deter- mination, maneuver planning, and general mission analysis. Advanced concepts for flight dynamics are developed and studied in the STL. Software systems produced in this facility include simulators, systems requiring special architectures (e.g., embedded systems), flight
FLIGHT DYNAMICS MISSION SUPPORT REQUIREMENTS
SYSTEMS DEVELOPMENT
FLIGHT DYNAMICS FACILITY
SYSTEMS TECHNOLOGY LABORATORY
> MISSION SUPPORT SOFTWARE
• DEVELOPMENT AND MAINTENANCE OF OPERATIONAL SYSTEMS
■ MISSION ANALYSIS AND OPERATIONS
FUTURE NEEDS
• STABLE/UNCHANGING HARDWARE
PROVEN TECHNOLOGY
• ADVANCED SYSTEMS
• RESEARCH AND DEVELOPMENT
• NEW TOOLS, METHODS. LANGUAGES
■ EXTENSIVE TOOLSETS FOR DEVELOPMENT
• SEL DATABASE
ADVANCED TECHNOLOGY
Figure 1-1. The SEL Software Engineering Environment
PRECEDES PAGE BLANK NOT FILMED
Section 1 - Introduction
dynamics utilities, and projects supporting advanced system studies. The STL also hosts the SEL database and the entire set of SEL research tools.
This revised edition of the Recommended Approach to Software Development reflects the evolution in life cycle, development methodology, and tools that has taken place in these environments in recent years. During this time, Ada and object-oriented design (OOD) methodologies have been introduced and used successfully. The potential for reuse of requirements, architectures, software, and documentation has been, and continues to be, studied and exploited. Ongoing studies also include experiments with the Cleanroom methodology (References 2 through 4), formal inspection, and computer-aided software engineering (CASE) tools.
Because the SEL's focus is process improvement, it is a catalyst for this evolution. The SEL continuously conducts experiments using the actual, production environment. The lessons learned from these experiments are routinely fed back into an evolving set of standards and practices that includes the Recommended Approach.
As these studies are confined to flight dynamics applications, readers of this document are cautioned that the guidance presented here may not always be appropriate for environments with significantly different characteristics.
DOCUMENT OVERVIEW
This document comprises 10 sections. Sections 3 through 9 parallel the phases of the software development life cycle through acceptance testing, and discuss the key activities, products, reviews, methodologies, tools, and metrics of each phase.
Section 1 presents the purpose, organization, and intended audience for the document.
Section 2 provides an overview of the software development
life cycle. The general goals of any software development effort are discussed, as is the necessity of tailoring the life cycle to adjust to projects of varying size and complexity.
Section 3 provides guidelines for the requirements definition phase. Generation of the system and operations concept and the requirements and specifications documents are covered. The purpose and format of the system concept and requirements reviews are oudined.
Section 1 - Introduction
r
(
REFERENCE
Section 4 discusses the key activities and products of the requirements analysis phase: requirements classifications, walk-throughs, functional or object-oriented analysis, the requirements analysis report, and the software specifications review.
Section 5 presents the recommended approach to preliminary design. The activities, products, and methodologies covered include structured and object-oriented design, reuse analysis, design walk-throughs, generation of prolog and program design language, the preliminary design report, and the preliminary design review.
Section 6 provides comparable material for the detailed design phase. Additional topics include the build test plan, completion of prototyping activities, the critical design review, and the detailed design document.
Section 7 contains guidelines for implementation of the
designed software system. Coding, code reading, unit testing, and integration are among the activities discussed. The system test plan and user's guide are summarized.
Section 8 addresses system testing, including test plans, testing methodologies, and regression testing. Also covered are preparation of the system description document and finalization of the acceptance test plan.
Section 9 discusses the products and activities of the acceptance testing phase: preparing tests, executing tests, evaluating results, and resolving discrepancies.
Section 10 itemizes key DOs and DON'Ts for project success.
A list of acronyms, references, a bibliography of SEL literature, and an index conclude this document.
\
IB
Recent SEL papers on software maintenance include "Measurement Based Improvement of Maintenance in the SEL." and "Towards Full Life Cycle Control, " both by Rombach, Ulery, and Valett. See References 5 and 6.
Although the maintenance and operation phase is beyond the scope of the current document, efforts are now underway in the SEL to study this important part of the life cycle. The results of these studies will be incorporated into a future edition.
i
o a
3 a
c
o
3
Mllll II MM III M AIM Ullll III
.Jllll
M\
A\t\ mil , , jMiliil
Jllll nil
II III III
Jill II
■III!
Section 2 - Life Cycle
SECTION 2
THE SOFTWARE DEVELOPMEISTT LIFE CYCLE
The flight dynamics software development process is modeled as a series of eight sequential phases, collectively referred to as the software development life cycle:
I 1. Requirements Definition | — ^ 2jRequirementsAnalysjs^^I
SjPrefirninaryDesign
4. Detailed Design
5. Implementation
6. System Testing
7. Acceptance Testing
1-
8. Maintenance & Operational
Each phase of the software development life cycle is characterized by specific activities and the products produced by those activities.
As shown in Figure 2-1, these eight phases divide the software life cycle into consecutive time periods that do not overlap. However, the activities characteristic of one phase may be performed in other phases. Figure 2-1 graphs the spread of activities throughout the development life cycle of typical flight dynamics systems. The figure shows, for example, that although most of the work in analyzing requirements occurs during the requirements analysis phase, some of that activity continues at lower levels in later phases as requirements evolve.
PRECEDING PAGE BLAriK NOT FJLMED
Section 2 - Life Cycle
REQUIREMENTS
DEFW4TTION
PHASE
■ A ■ DETAILED ■
■ f* DESIGN ■
■ I ■ PHASE ■ PRELIMINARY DESIGN PHASE
IMPLEMENTATION PHASE
SYSTEM B ACCEPTANCE ■ MAINTENANCE AND TEST B TEST PHASE ■ OPERATION PHASE PHASE ■ ■
REQUIREMENTS ANALYSIS PHASE
CALENDAR TIME
Example At the end of the Implementation phase (5th dashed line), approximately 46% of the staff are Involved In system testing; approximately 16% are preparing for acceptance testing; approximately 7% are addressl ng requirements changes or problems; approximately 12% are designing modifications; and approximately 20% are coding, code reading, unit testing, and Integrating changes. Data are shown only for the phases of the software life cycle for which the SEL has a representative sample.
Figure 2-1. Activities by Percentage of Total Development Staff Effort
PHASES OF THE LIFE CYCLE
The eight phases of the software development life cycle are defined in the following paragraphs.
Requirements Definition
Requirements definition is the process by which the needs of the customer are translated into a clear, detailed specification of what the system must do. For flight dynamics applications, the requirements definition phase begins as soon as the mission task is established. A team of analysts studies the available information about the mission and develops an operations concept. This includes a timeline for mission events, required attitude maneuvers, the types of computational processes involved, and specific operational scenarios. The functions that the system must perform are defined down to the level of a subsystem (e.g., a telemetry processor).
1
Section 2 - Life Cycle
r
(
NOTE
\
In this document, the term analyst refers to those specialists in flight dynamics (astronomers, mathematicians, physicists, and engineers) who determine the detailed requirements of the system and perform acceptance tests. For these activities, analysts work in teams (e.g., the requirements definition team) and function as agents for the end users of the system.
NOTE
"\
In each phase of the life cycle, certain milestones must be reached in order to declare the phase complete. Because the life cycle is sequential, these exit criteria are also the entry criteria for the following phase. In this document, entry and exit criteria are shown in the summary tables on the first page of Sections 3 through 9. A brief discussion of the phase's exit criteria is provided at the conclusion of each section.
Working with experienced developers, analysts identify any previously developed software that can be reused on the current project. The advantages and disadvantages of incorporating the existing components are weighed, and an overall architectural concept is negotiated. The results of these analyses are recorded in the system and operations concept (SOC) document and assessed in the system concept review (SCR).
Guided by the SOC, a requirements definition team derives a set of system-level requirements from documents provided by the mission project office. A draft version of the requirements is then recast in terms suitable for software design. These specifications define what data will flow into the system, what data will flow out, and what steps must be taken to transform input to output. Supporting mathematical information is included, and the completed requirements and specifications document is published. The conclusion of this phase is marked by the system requirements review (SRR), during which the requirements and specifications for the system are evaluated.
Requirements Analysis
The requirements analysis phase begins after the SRR. In this phase, the development team analyzes the requirements and specifications document for completeness and feasibility. The development team uses structured or object-oriented analysis and a requirements classification methodology to clarify and amplify the document. Developers work closely with the requirements definition team to resolve ambiguities, discrepancies, and to-be- determined (TBD) requirements or specifications.
The theme of reuse plays a prominent role throughout the requirements analysis and design phases. Special emphasis is placed on identifying potentially reusable architectures, designs, code, and approaches. (An overview of reuse in the life cycle is presented later in this section.)
When requirements analysis is complete, the development team prepares a summary requirements analysis report as a basis for preliminary design. The phase is concluded with a software specifications review (SSR), during which the development team
Section 2 - Life Cycle
presents the results of their analysis for evaluation. The requirements definition team then updates the requirements and specifications document to incorporate any necessary modifications.
Preliminary Design
The baselined requirements and specifications form a contract between the requirements definition team and the development team and are the starting point for preliminary design. During this phase, members of the development team define the software architecture that will meet the system specifications. They organize the requirements into major subsystems and select an optimum design from among possible alternatives. All internal and external interfaces are defined to the subsystem level, and the designs of high-level functions/objects are specified.
The development team documents the high-level design of the system in the preliminary design report. The preliminary design phase culminates in the preliminary design review (PDR), where the development team formally presents the design for evaluation.
Detailed Design
During the detailed design phase, the development team extends the software architecture defined in preliminary design down to the unit level. By successive refinement techniques, they elaborate the preliminary design to produce "code-to" specifications for the software. All formalisms for the design are produced, including the following:
• Functional or object-oriented design diagrams
• Descriptions of all user input, system output (for example, screen, printer, and plotter), and input/output files
• Operational procedures
• Functional and procedural descriptions of each unit
• Descriptions of all internal interfaces among units
The development team documents these design specifications in the detailed design document that forms the basis for implementation. At the critical design review (CDR), which concludes this phase, the detailed design is examined to determine whether levels of detail and completeness are sufficient for coding to begin.
r
0
DEFINITIONS
\
Throughout this document, the term unit is used to designate any set of program statements that are logically treated as a whole. A main program, a subroutine, or a subprogram may each be termed a unit. A module'n a collection of logically related units. Component is used in its English language sense to denote any constituent part.
Section 2 - Life Cycle
Implemen ta tio n
In the implementation (code, unit testing, and integration) phase, the developers code new components from the design specifications and revise existing components to meet new requirements. They integrate each component into the growing system, and perform unit and integration testing to ensure that newly added capabilities function correctly.
In a typical project, developers build several subsystems simultaneously from individual components. The team repeatedly tests each subsystem as new components are coded and integrated into the evolving software. At intervals, they combine subsystem capabilities into a complete working system for testing end-to-end processing capabilities. The sequence in which components are coded and integrated into executable subsystems and the process of combining these subsystems into systems are defined in an implementation plan that is prepared by development managers during the detailed design phase.
The team also produces a system test plan and a draft of the user's guide in preparation for the system testing phase that follows. Implementation is considered complete when all code for the system has been subjected to peer review, tested, and integrated into the system.
System Testing
During the system testing phase, the development team validates the completely integrated system by testing end-to-end capabilities according to the system test plan. The system test plan is based on the requirements and specifications document. Successfully completing the tests specified in the test plan demonstrates that the system satisfies the requirements.
In this phase, the developers correct any errors uncovered by system tests. They also refine the draft user's guide and produce an initial system description document. System testing is complete when all tests specified in the system test plan have been run successfully.
Acceptance Testing
In the acceptance testing phase, the system is tested by an independent acceptance test team to ensure that the software meets all requirements. Testing by an independent team (one that does not have the developers' preconceptions about the functioning of the system) provides assurance that the system satisfies the intent of the
Section 2 - Life Cycle
original requirements. The acceptance test team usually consists of analysts who will use the system and members of the requirements definition team.
The tests to be executed are specified in the acceptance test plan prepared by the acceptance test team before this phase. The plan is based on the contents of the requirements and specifications document and approved specification modifications.
During acceptance testing, the development team assists the test team and may execute acceptance tests under its direction. Any errors uncovered by the tests are corrected by the development team. Acceptance testing is considered complete when the tests specified in the acceptance test plan have been run successfully and the system has been formally accepted. The development team then delivers final versions of the software and the system documentation (user's guide and system description) to the customer.
Maintenance and Operation
At the end of acceptance testing, the system becomes the responsibility of a maintenance and operation group. The activities conducted during the maintenance and operation phase are highly dependent on the type of software involved. For most flight dynamics software, this phase typically lasts the lifetime of a spacecraft and involves relatively few changes to the software. For tools and general mission support software, however, this phase may be much longer and more active as the software is modified to respond to changes in the requirements and environment.
The maintenance and operation phase is not specifically addressed in this document. However, because enhancements and error corrections also proceed through a development life cycle, the recommended approach described here is, for the most part, applicable to the maintenance and operation phase. The number and formality of reviews and the amount of documentation produced during maintenance and operation vary depending on the size and complexity of the software and the extent of the modifications.
/'note \
' Recent SEL studies have shown that most of the effort in initial maintenance of flight dynamics systems is spent in enhancing the system after launch to satisfy new requirements for long-term operational support. Such enhancements are usually effected without radically altering the architecture of the system. Errors found during the maintenance and operation phase are generally the same type of faults as are uncovered during development, although they require more effort to repair.
10
I
Section 2 - Life Cycle
TAILORING THE LIFE CYCLE
One of the key characteristics that has shaped the SEL's recommended approach to software development is the homo- geneous nature of the problem domain in the flight dynamics environment. Most software is designed either for attitude determination and control for a specific mission, for mission-general orbit determination and tracking, or for mission planning. These projects progress through each life cycle phase sequentially, generating the standard documents and undergoing the normal set of reviews.
r
(
RULE
\
The software development/ management plan (SDMP) must describe how the life cycle will be tailored for a specific project. See Section 4 for more details.
Certain projects, however, do not fit this mold. Within the STL, experiments are conducted to study and improve the development process. Advanced tools are developed. For these development efforts — prototypes, expert systems, database tools, Cleanroom experiments, etc. — the life cycle and the methodologies it incorporates often need adjustment. Tailoring allows variation in the level of detail and degree of formality of documentation and reviews, which may be modified, replaced, or combined in the tailoring process. Such tailoring provides a more exact match to unique project requirements and development products at a lower overall cost to the project without sacrificing quality.
The following paragraphs outline general guidelines for tailoring the life cycle for projects of varying size and type. Additional recommendations may be found throughout this document, accompanying discussions of specific products, reviews, methods, and tools.
Builds and Releases
The sizes of typical flight dynamics projects vary considerably. Simulators range from approximately 30 thousand source lines of code (KSLOC) to 160 KSLOC. Attitude ground support systems for specific missions vary between 130 KSLOC and 300 KSLOC, while large mission-general systems may exceed 1 million SLOC. The larger the project, the greater the risk of schedule slips, requirements changes, and acceptance problems. To reduce these risks, the implementation phase is partitioned into increments tailored to the size of the project.
11
Section 2 - Life Cycle
Flight dynamics projects with more than 10 KSLOC are implemented in builds. A build is a portion of a system that satisfies, in part or completely, an identifiable subset of the specifications. Specifications met in one build also are met in all successor builds. The last build, therefore, is the complete system.
A release is a build that is delivered for acceptance testing and subsequently released for operational use. Projects of fewer than 300 KSLOC are usually delivered in a single release, unless otherwise dictated by scheduling (e.g., launch) considerations or by TBD requirements. Large projects (more than 300 KSLOC) are generally delivered in multiple releases of 300 to 500 KSLOC each.
Builds within large projects may last up to 6 months. Builds within small projects may be only 2 to 3 months in duration.
r
(
NOTE
1
Reviews are recommended for each build. The suggested format and contents of build design reviews are provided in Section 7.
r
(
NOTE
"Y
Guidelines for tailoring the development approach (including reviews, documentation, and testing) for projects of differing scope and function are provided throughout this document. Look for the scissors symbol in the margin.
Reviews
Reviews are conducted to ensure that analysts and developers understand and fulfill customer needs. Because reviews are designed to assist developers, not to burden them unnecessarily, the number of reviews held may vary from project to project. For tools development, the requirements, requirements analysis, and preliminary design might be reviewed together at PDR. For small projects spanning just several months, only two reviews may be applicable — the SRR and CDR. For very large projects, a CDR could (and should) be held for each major release and/or subsystem to cover all aspects of the system and to accommodate changing requirements.
The criteria used to determine whether one or more reviews can be combined depend on the development process and the life cycle phase. In the requirements analysis phase, for example, answers to the following questions would help determine the need for a separate SSR:
• Are there outstanding analysis issues that need to be reviewed?
• How much time will there be between the start of requirements analysis and the beginning of design?
• How stable are the requirements and specifications?
12
Section 2 - Life Cycle
On small projects, technical reviews can be no more formal than a face-to-face meeting between the key personnel of the project and the customer technical representative. On typical flight dynamics projects, however, reviews are formalized and follow specific formats. Guidelines for these reviews are provided in Sections 3 through 9.
Documentation
On small projects, technical documentation is less formal than on medium or large projects, and fewer documents are published. Documents that would normally be produced separately on larger projects are combined. On a small research project, a single design document may replace the preliminary design report, detailed design document, and system description.
Testing and Verification
Independent testing is generally not performed on small-scale, tool- development efforts. Test plans for such projects can be informal. Although code reading is always performed on even the smallest project, units are often tested in logically related groups rather than individually, and inspections are usually conducted in informal, one- on-one sessions.
Configuration Management and Quality Assurance
Configuration management encompasses all of the activities concerned with controlling the contents of a software system. These activities include monitoring the status of system components, preserving the integrity of released and developing versions of a system, and governing the effects of changes throughout the system. Quality assurance activities ensure that software development processes and products conform to established technical requirements and quality standards.
All software and documentation that are developed for delivery are generally subject to formal configuration management and quality assurance controls. Tools developed exclusively for internal use are exempt, unless the tool is required to generate, run, or test a deliverable system.
On medium and small projects, configuration control may be performed by a designated member of the development team — a practice that is strongly discouraged on a large project. Similarly, the quality assurance function may be assigned to a team member with other responsibilities or may be handled by the technical leader.
13
Section 2 - Life Cycle
Prototyping
A prototype is an early experimental model of a system, system component, or system function that contains enough capabilities for it to be used to establish or refine requirements or to validate critical design concepts. In the flight dynamics environment, prototypes are used to (1) mitigate risks related to new technology (e.g., hardware, language, design concepts) or (2) resolve requirements issues. In the latter case, entire projects may be planned as prototyping efforts that are designed to establish the requirements for a later system.
Unless the end product of the entire project is a prototype, prototyping activities are usually completed during the requirements analysis and design phases. The prototyping activity has its own, usually informal, life cycle that is embedded within the early phases of the full system's life cycle. If any portion of the prototype is to become part of the final system, it must be validated through all the established checkpoints (design reviews, code reading, unit testing and certification, etc.). As a rule, such prototyping activities should require no more than 15 percent of the total development effort.
For projects in which the end product is a prototype, however, an iterative life cycle may be preferable. This is particularly true when a new user interface is a significant component of the system. An initial version of the prototype is designed, implemented, and demonstrated to the customer, who adds or revises requirements accordingly. The prototype is then expanded with additional builds, and the cycle continues until completion criteria are met.
r
r
RULE
\
Ail prototyping activities must be planned and controlled. The plan must define the purpose and scope of the prototyping effort, and must establish specific completion criteria. See Section 4 for more details.
f
WHEN TO PROTOTYPE
"I
*P& a rule of thumb, use prototyping whenever
• the project involves new technology, e.g., new hardware, development language, or system architecture
• the requirements are not understood
• there are major, unresolved issues concerning performance, reliability, or feasibility
• the user interface is critical to system success or is not clearly understood
Tailoring the life cycle for any type of prototyping requires careful planning. The more new technology that is to be used on a project, the greater the prototyping effort. The larger the prototyping effort, the more formalized must be its planning, development, and management. The results of even the smallest prototyping effort must always be documented. Lessons learned from the prototype are incorporated into plans for subsequent phases and are included in the project history. See Section 4 for additional guidance on planning and documenting prototyping activities.
m i
14
! i
Section 2 - Life Cycle
f KEY REUSE ELEMENTS ^
' Analyze these key elements of a project for possible reuse:
• requirements characteristics
• software architecture
• software development process
• design architecture or concepts
• test plans and procedures
• code
• user documentation
• staff
REUSE THROUGHOUT THE LIFE CYCLE
From the beginning to the end of the life cycle, the approach to software development recommended by the SEL stresses the principle of reuse. Broadly speaking, the reuse of existing experience is a key ingredient to progress in any area. Without reuse, everything must be relearned and re-created. In software development, reuse eliminates having to "reinvent the wheel" in each phase of the life cycle, reducing costs and improving both reliability and productivity.
Planning for reuse maximizes these benefits by allowing the cost of the learning curve in building the initial system to be amortized over the span of follow-on projects. Planned reuse is a primary force behind such recent technologies as object-oriented design and Ada.
All experience and products of the software development life cycle — specifications, designs, documentation, test plans, as well as code — have potential for reuse. In the flight dynamics environment, particular benefits have been obtained by reusing requirements and specifi- cations (i.e., formats, key concepts, and high- level functionality) and by designing for reuse (see References 7 through 10).
O
Figure 2-2 shows how reuse activities fit into the software development life cycle. The top half of the figure contains activities that are conducted to enable future reuse. The lower half shows activities in which existing software is used in the system under development. These activities are outlined in the following paragraphs.
domain analysis
requirements generalization
Activities That Enable Future Reuse
Domain analysis is the examination of the application domain of the development organization to identify common requirements and functions. It is usually performed during the requirements definition and analysis phases, but it may also be conducted as a separate activity unconnected to a particular development effort. Domain analysis produces a standard, general architecture or model that incorporates the common functions of a specific application area and can be tailored to accommodate differences between individual projects. It enables requirements generalization, i.e., the preparation of requirements and specifications in such a way that they cover a selected "family" of projects or missions.
15
Section 2 - Life Cycle
SRR
SSR
ATRR
Enabling
Reusing
DOMAIN ANALYSIS
GENERALIZATION OF
REQUIREMENTS AND
SPECIFICATIONS
REUSE ANALYSIS
{subsystem level)
REQUIREMENTS
DEFINITION PHASE
T
DESIGNING FOR REUSE
REUSE VERIFICATION
[component & unit level)
VERBATIM REUSE Unking to library unitsl
MODIFICATION OF REUSABLE UNITS
EXTRACTION
OF CANDIDATES
FOR THE REUSE
I L'BRARY
A DETAILED DESIGN PHASE PRELIMINARY DESIGN PHASE REQUIREMENTS
IMPLEMENTATION- PHASE
SYSTEM
TESTING
PHASE
J
REUSE PRESERVATION
MAINTENANCE
AND OPERATION
PHASE
ACCEPTANCE TESTING PHASE
ANALYSIS PHASE
Figure 2-2. Reuse Activities Within the Life Cycle
Software not originally intended for reuse is more difficult to incorporate into a new system than software explicitly designed for reuse. Designing for reuse provides modularity, standard inter- faces, and parameterization. Design methods that promote reusability are described in References 9 and 1 1 .
Reuse libraries hold reusable source code and associated requirements, specifications, design documentation, and test data. In addition to storing the code and related products, the library contains a search facility that provides multiple ways of accessing the software (e.g., by keyword or name). On projects where reuse has been a design driver, extraction of candidate software for inclusion in the reuse library takes place after system testing is complete.
designing for reuse
reuse libraries
Reuse on Current Projects
During the requirements definition and analysis phases, reuse analysis is performed to determine which major segments (subsystems) of existing software can be used in the system to be developed. In the design phases, developers verify this analysis by examining each reusable element individually. During the preliminary design phase, developers evaluate major components to determine whether they can be reused verbatim or must be modified; individual units from the reuse library are examined during the detailed design phase.
reuse analysis and verification
16
Section 2 - Life Cycle
reuse preservation
Software may be reused verbatim or may be modified to fit the needs of the current project. During the implementation phase, developers integrate existing, unchanged units into the developing system by linking directly to the reuse library. Modified software, on the other hand, must be subjected to peer review and unit testing before being integrated.
A final reuse activity takes place during the maintenance and operation phase of the life cycle. Through the changes that it implements, the maintenance team can positively or negatively affect the reusability of the system; "quick fixes", for example, may complicate future reuse. Reuse preservation techniques for maintenance use many of the same practices that promote reuse during the analysis, design, and implementation phases.
r
(
NOTE
MEASURES
Measures of project progress and viability are key to the effective management of any software development effort. In each phase of the life cycle, there are certain critical metrics that a manager must examine to evaluate the progress, stability, and quality of the development project.
\
Sections 3 through 9 of this document provide detailed information about the objective measures used in each phase. Look for the MEASURES heading and symbol.
Both objective and subjective data are measured. Objective data are actual counts of items (e.g., staff hours, SLOC, errors) that can be independently verified. Subjective data are dependent on an individual's or group's assessment of a condition (e.g., the level of difficulty of a problem or the clarity of requirements). Together, these data serve as a system of checks and balances. Subjective data provide critical information for interpreting or validating objective data, while objective data provide definitive counts that may cause the manager to question his or her subjective understanding and to investigate further.
Objective measures can be further classified into two groups: those that measure progress or status and those that measure project quality (e.g., stability, completeness, or reliability). Progress measures, such as the number of units coded or the number of tests passed, are evaluated against calculations of the total number of items to be completed. Quality measures, on the other hand, are
17
Section 2 - Life Cycle
Table 2-1. Measures Recommended by the SEL
|
MEASURES |
MEASURE |
SOURCE |
FREQUENCY |
MAJOR APPLICATION |
|
CLASS |
||||
|
ESTIMATES |
Estimates of: •Total SLOC (new, modified, reused) • Total units • Total effort • Major dates |
Managers |
Monthly |
• Project stability • Planning aid |
|
RESOURCES |
• Staff hours (total & by activity) |
Developers |
Weekly |
• Project stability • Repianning indicator |
|
• Computer use |
Automated tool |
Weekly |
• Effectiveness/impact of the development process being applied |
|
|
STATUS |
• Requirements (growth, TBDs, changes, Q&As) |
Managers |
Biweekly |
• Project progress • Adherence to defined process |
|
• Units designed, |
Developers |
Biweekly |
• Stability and quality of |
|
|
coded, tested |
requirements |
|||
|
• SLOC (cumulative) |
Automated |
Weekly |
||
|
• Tests (complete, |
Developers |
Biweekly |
||
|
passed) |
||||
|
ERRORS/ |
• Errors (by |
Developers |
By event |
• Effectiveness/impact of the |
|
CHANGES |
category) |
development process |
||
|
• Changes (by |
Developers |
By event |
• Adherence to defined |
|
|
category) |
process |
|||
|
• Changes (to source) |
Automated |
Weekly |
||
|
FINAL |
Actuals at completion: |
Managers |
1 time, at |
■ Build predictive models |
|
CLOSE-OUT |
■ Effort • Size (SLOC, units) • Source characteristics • Major dates |
completion |
• Plan/manage new projects |
only useful if the manager has access to models or metrics that represent what should be expected.
In the SEL, measurement data from current and past projects are stored in a project histories database. Using information extracted from such a database, managers can gauge whether measurement trends in the current project differ from the expected models for the development environment. (See Section 6 of Reference 12.)
The management measures recommended by the SEL are listed in Table 2-1. Figure 2-3 shows in which phases of the life cycle each of these measures is collected.
As Table 2-1 shows, developers are responsible for providing many of the measures that are collected. In the SEL, developers use various data collection forms for this purpose. The individual forms are discussed in the sections of this document covering the life-cycle phases to which they apply.
18
Section 2 - Life Cycle
STATUS
ERRORS/ CHANGES
k\R,qulr.^ly<^
"E
Units designed
«*$
VojTests run/paseedjv
I
jChanges and errors <by category! Changes to source code
REQUIREMENTS DEFINITION
REQUIRE MENTS ANALVSIS
PRELIMI NARV DESIGN
DETAILED DESIGN
IMPLEMENTATION
ACCEPTANCE TESTING
MAINTENANCE AND OPERATION
Figure 2-3. Graph Showing in Which Life-Cycle Phases Each Measure Is Collected
EXPERIMENTATION
Measurement is not only essential to the management of a software development effort; it is also critical to software process improvement. In the SEL, process improvement is a way of life. Experiments are continually being conducted to investigate new software engineering technologies, practices, and tools in an effort to build higher-quality systems and improve the local production process. The SEL's ongoing measurement program provides the baseline data and models of the existing development environment against which data from experimental projects are compared.
For several years, the SEL has been conducting experiments and measuring the impact of the application of the Cleanroom methodology (References 2, 3, and 4), which was developed in the early 1980s by Harlan Mills. The goal of the Cleanroom methodology is to build a software product correctly the first time. Cleanroom stresses disciplined "reading" techniques that use the human intellect to verify software products; testing is conducted for the purpose of quality assessment rather than as a method for detecting and repairing errors.
The Cleanroom methodology is still in the early stages of evaluation by the SEL. Although some of the methods of Cleanroom are the same as existing methods in the SEL's recommended approach — e.g., code reading — other aspects remain experimental.
19
Section 2 - Life Cycle
Consequently, the Cleanroom methodology is used throughout this document as an example of the integral aspect of experimentation and process improvement to the SEL's recommended approach. Variations in life cycle processes, methods, and tools resulting from the application of Cleanroom will be highlighted. Look for the experimentation symbol.
r
r
DEFINITION
1
The term Cleanroomwas borrowed from integrated circuit production. It refers to the dust-free environments in which the circuits are assembled.
i
20
Section 3 - Requirements Definition
IK
CYCLE
PHASES
REQUIREMENTS DEFINITION
REQUfRE.
MENTS
ANALYSIS
PRELIMI- NARY
DESIGN
DETAILED DESIGN
IMPLEMENTATION
SYSTEM TESTING
ACCEPTANCE
TESTtNO
SECTION 3
THE REQUIREMENTS DEFINITION PHASE
mm
ENTRY CRITERIA
• Problem/project description completed
• Project approved
EXIT CRITERIA
System and operations concept completed
SRR completed
Requirements and specifications baselined |
PRODUCTS
> System and operations concept document • Requirements and specifications document
MEASURES
• Staff hours
• Number of requirements defined vs. estimated total requirements
• Percentage of requirements with completed specifications
IjyUlLUUIULIJI
METHODS AND TOOLS
■ Structured or object-oriented analysis
■ Walk-throughs • Prototyping
mmmmmm
KEY ACTIVITIES
Requirements Definition Team
• Develop a system concept
• Prepare the reuse proposal
• Develop an operations concept
• Define the detailed requirements
• Derive the specifications
• Conduct the SCR and SRR
Management Team
• Develop a plan for the phase
• Staff and train the requirements definition team
• Interact with the customer
• Evaluate progress and products
• Control major reviews
WPM#^HW%piPIP^%^liiiil^
21
Section 3 - Requirements Definition
OVERVIEW
The purpose of the requirements definition phase is to produce a clear, complete, consistent, and testable specification of the technical requirements for the software product.
Requirements definition initiates the software development life cycle. During this phase, the requirements definition team uses an iterative process to expand a broad statement of the system requirements into a complete and detailed specification of each function that the software must perform and each criterion that it must meet. The finished requirements and specifications, combined with the system and operations concept, describe the software product in sufficient detail so that independent software developers can build the required system correctly.
The starting point is usually a set of high-level requirements from the customer that describe the project or problem. For mission support systems, these requirements are extracted from project documentation such as the system instrumentation requirements document (SERD) and the system operations requirements document (SORD). For internal tools, high-level requirements are often simply a list of the capabilities that the tool is to provide.
In either case, the requirements definition team formulates an overall concept for the system by examining the high-level requirements for similarities to previous missions or systems, identifying existing software that can be reused, and developing a preliminary system architecture. The team then defines scenarios showing how the system will be operated, publishes the system and operations concept document, and conducts a system concept review (SCR). (See Figure 3-1.)
Following the SCR, the team derives detailed requirements for the system from the high- level requirements and the system and operations concept. Using structured or object- oriented analysis, the team specifies the software functions and algorithms needed to satisfy each detailed requirement.
(note
r
In the flight dynamics environment, membership in the teams that perform the technical activi- ties of software development overlap: The overlap ensures Ijhat experienced...
flMOTE (cont.)
\
analysts from the *N requirements
definition team plan acceptance tests, and that developers assist in defining requirements, planning for reuse, and supporting acceptance testing, j
22
Section 3 - Requirements Definition
PROJECT OR PROBLEM DESCRIPTION
ENGINEERING STUDY REPORTS
SCR-HARDCOPY-MATERIALS
NOTE: In this figure, as In all data flow diagrams (DFDs) in this document, rectangles denote external entities, circles represent processes, and parallel lines are used for data stores (in this case, documents). The processes labelled 3.1, 3.2, and 3.3 are described in the KEY ACTIVITIES subsection below. The SCR is described under REVIEWS and the system and operations concept document is covered in PRODUCTS.
Figure 3-1. Generating the System and Operations Concept
When the specifications are complete, the requirements definition team publishes the requirements and specifications document in three parts: (1) the detailed requirements, (2) the functional or object-oriented specifications, and (3) any necessary mathematical background information. At the end of the phase, the team conducts a system requirements review (SRR) to demonstrate the completeness and quality of these products. (See Figure 3-2.)
23
Section 3 - Requirements Definition
PROJECT OR PROBLEM
SYSTEM AND OPERATIONS CONCEPT DOCUMENT
INFORMATION FROM PREVIOUS PROJECTS
ITEMIZED HOH-LEVEL
INTERFACE CONTROL DOCUMENTS
SRR PARTICIPANTS
SRR HARDCOPY MATERIALS
NOTE: The processes labelled 3.S, 3.6, and 3.7 are discussed In the KEY ACTIVITIES subsection. The requirements and specifications document is described under the heading PRODUCTS. The REVIEWS subsection covers the SRR.
Figure 3-2. Developing Requirements and Specifications
24
Section 3 - Requirements Definition
KEYACTTVTTIES
The key technical and managerial activities of the requirements definition phase are itemized below.
Activities of the Requirements Definition Team
• Develop a system concept. Collect and itemize all high-level requirements for the system. Describe the basic functions that the system must perform to satisfy these high-level requirements. Address issues such as system lifetime (usage timelines), performance, security, reliability, safety, and data volume.
From this functional description, generate an ideal, high-level system architecture identifying software programs and all major interfaces. Allocate each high-level requirement to software, hardware, or a person. Specify the form (file, display, printout) of all major data interfaces.
r
r TAILORING NOTE ^
On small projects that are developing tools or prototypes, requirements definition and analysis are often combined into a single phase. On such projects, developers generally perform all requirements definition activities.
r
(
REUSE NOTE
©
^
Although use of existing software can reduce effort significantly, some compromises may be necessary. Ensure that all tradeoffs are well understood. Avoid these two pitfalls:
• Failing to make reasonable compromises, thus wasting effort for marginal improvement in quality or functionality
• Making ill-advised compromises that save development effort at the cost of significantly degrading functionality or performance
Prepare the reuse proposal. Review the requirements and specifications, system descriptions, user's guides, and source code of related, existing systems to identify candidates for reuse. For flight dynamics mission support systems, this involves reviewing support systems for similar spacecraft. Select strong candidates and estimate the corresponding cost and reliability benefits. Determine what compromises are necessary to reuse software and analyze the tradeoffs.
Adjust the high-level architecture to account for reuseable software. Record the results of all reuse analysis in a reuse proposal that will be included in the system and operations concept document.
Develop an operations concept. This clearly defines how the system must operate within its environment. Include operational scenarios for all major modes of operation (e.g., emergency versus normal). Be sure to include the end-user in this process. Conduct an SCR.
25
Section 3 - Requirements Definition
Define the detailed requirements. Based on the high-level requirements and the system concept and architecture, define all software requirements down to the subsystem level. If the system is large (with many subsystems) or if it will interface with other systems, explicitly define all external interfaces.
r
NOTE
f NOTE
1
Sea the PRODUCTS subsection below for detailed contents of the system and operations concept as well as the requirements and functional specifications documents.
"Y
The SCR and SRR are covered in detail in the REVIEWS subsection.
Q
Determine system performance and reliability requirements. If certain acceptance criteria apply to a requirement (e.g., meeting a particular response time), specify the test criteria with the requirement. Identify all intermediate products needed to acceptance test the system.
Derive the functional specifications for the system from the requirements. Identify the primary input and output data needed to satisfy the requirements. Use structured or object-oriented analysis to derive the low-level functions and algorithms the software must perform. Define all reports and displays and indicate which data the user must be able to modify.
Keep the specifications design-neutral and language-neutral; i.e., concentrate on what the software needs to do, rather than how it will do it. Create a traceability matrix to map each low-level function or data specification to the requirements it fulfills.
Ensure that all requirements and specifications are given a thorough peer review. Watch for interface problems among major functions and for specifications that are duplicated in multiple subsystems. Ensure compatibility and consistency in notation and level of accuracy among the specified algorithms.
Prepare the requirements and specifications document, including any necessary mathematical background information, as a basis for beginning software development.
TAILORING NOTE
\
On very large or complex projects, it is generally advisable to hold a preliminary system requirements review (PSRR) as soon as a draft of the requirements document is complete. This allows end-users and key developers to raise critical issues before requirements are finalized. See the REVIEWS subsection for additional information on the PSRR.
26
Section 3 - Requirements Definition
• Conduct the SRR and incorporate approved changes into the requirements and specifications. Place the document under configuration management as the system baseline.
Activities of the Management Team
The management activities performed during this phase pave the way for all future phases of the project's life cycle. Specifically, managers must accomplish the following:
• Develop a plan for the phase. (Detailed planning of the entire development effort is deferred to the requirements analysis phase, after system specifications have been defined.) Address the staffing of the teams that will perform the technical work, the groups and individuals that will interface with the teams, the technical approach, milestones and schedules, risk management, and quality assurance. List the reviews to be conducted and their level of formality.
• Staff and train the requirements definition team. Ensure that the team contains the necessary mix of skills and experience for the task. For mission support systems, the team should include analysts with strong backgrounds in mission analysis, attitude and orbit determination, and operations. The reuse working group must include key software developers as well as experienced analysts. Ensure that staff members have the necessary training in the procedures, methods, and tools needed to accomplish their goals.
.(
DEFINITION
\
'The toy developers who participate in reuse analysis and other requirements definition activities have special technical roles throughout the life cycle. The value of these application specialists lies in their specific knowledge and experience. On mission support projects, for example, the application specialist will not only have developed such software previously, but also will understand the complex mathe- matics and physics of flight dynamics. The application specialist often acts as a "translator," facilitating communications between analysts and developers.
Interact with the customer to assure visibility and resolution of all issues. Conduct regular status meetings and ensure communications among team members, managers, customers, and other groups working on aspects of the project.
Evaluate progress and products. Review the system and operations concept and the requirements and specifications. Collect progress measures and monitor adherence to schedules and cost.
Control major reviews. Ensure that key personnel are present at reviews, both formal and informal. Participate in the SCR and SRR.
27
Section 3 - Requirements Definition
METHODS AND TOOLS
The methods and tools used during the requirements definition phase are
• Structured or object-oriented analysis
• Walk-throughs
• Prototyping
Each is discussed below.
Analysis Methodologies
Structured analysis and object-oriented analysis are techniques used to understand and articulate the implications of the textual statements found in the requirements definition. The requirements definition team uses analysis techniques to derive the detailed specifications for the system from the higher-level requirements. The analysis methodology selected for the project should be appropriate to the type of problem the system addresses.
Functional decomposition is currently the most commonly used method of structured analysis. Functional decomposition focuses on processes, each of which represents a set of transformations of input to output. Using this method, the analyst separates the primary system function into successively more detailed levels of processes and defines the data flows between these processes. Authors associated with structured analysis include E. Yourdon, L. Constantine, and T. DeMarco (References 13 and 14). S. Mellor and P. Ward have published a set of real-time extensions to this method for event-response analysis (Reference 15).
Object-oriented analysis combines techniques from the realm of data engineering with a process orientation. This method defines the objects (or entities) and attributes of the real-world problem domain and their interrelationships. The concept of an object provides a means of focusing on the persistent aspect of entities — an emphasis different from that of structured analysis. An object-oriented approach is appropriate for software designed for reuse because specific objects can be readily extracted and replaced to adapt the system for other tasks (e.g., a different spacecraft). Details of the object-oriented approach may be found in References 11, 16, and 17.
In structured analysis, functions are grouped together if they are steps in the execution of a higher-level function. In object-oriented analysis, functions are grouped together if they operate on the same data abstraction. Because of this difference, proceeding from functional specifications to an object-oriented design may necessitate
structured analysis
object- oriented analysis
28
Section 3 - Requirements Definition
r
(
NOTE
\
CASE tools can greatly increase productivity, but they can only aid or Improve those activities that the team or individual knows how to perform manually. CASE tools cannot improve analysis, qualify designs or code, etc., if the user does not have have a clear definition of the manual process involved.
recasting the data flow diagrams. This is a significant amount of effort that can be avoided by assuming an object-oriented viewpoint during the requirements definition phase.
The diagramming capabilities of CASE tools facilitate application of the chosen analysis methodology. The tools provide a means of producing and maintaining the necessary data flow and object-diagrams online. They usually include a centralized repository for storing and retrieving definitions of data, processes, and entities. Advanced tools may allow the specifications themselves to be maintained in the repository, making it easier to trace the requirements to design elements.
Selected tools should be capable of printing the diagrams in a form that can be directly integrated into specifications and other documents. Examples of CASE tools currently used in the flight dynamics environment include System Architect and Software Through Pictures.
walk-throughs
inspections
Walk-throughs
In all phases of the life cycle, peer review ensures the quality and consistency of the products being generated. The SEL recommends two types of peer review — walk-throughs and inspections — in addition to formal reviews such as the SRR and CDR.
Walk-throughs are primarily conducted as an aid to understanding, so participants are encouraged to analyze and question the material under discussion. Review materials are distributed to participants prior to the meeting. During the meeting, the walk-through leader gives a brief, tutorial overview of the product, then walks the reviewers through the materials step-by-step. An informal atmosphere and a free interchange of questions and answers among participants fosters the learning process.
Inspections, on the other hand, are designed to uncover errors as early as possible and to ensure a high-quality product. The inspection team is a small group of peers who are technically competent and familiar with the application, language, and standards used on the project. The products to be reviewed (e.g., requirements, design diagrams, or source code) are given to the inspection team several days before the meeting. Inspectors examine these materials closely, noting all errors or deviations from
29
Section 3 - Requirements Definition
standards, and they come to the review meeting prepared to itemize and discuss any problems.
In both walk-throughs and inspections, a designated team member records the minutes of the review session, including issues raised, action items assigned, and completion schedules. Closure of these items is addressed in subsequent meetings.
In the requirements definition phase, walk-throughs of the requirements and specifications are conducted to ensure that key interested parties provide input while requirements are in a formative stage. Participants include the members of the requirements definition team, representatives of systems that will interface with the software to be developed, and application specialists from the development team.
Prototyping
During the requirements definition phase, prototyping may be needed to help resolve requirements issues. For mission support systems, analysts use prototyping tools such as MathCAD to test the mathematical algorithms that will be included in the specifications. For performance requirements, platform-specific performance models or measurement/monitoring tools may be used.
MEASURES
Objective Measures
Three progress measures are tracked during the requirements definition phase:
• Staff hours — i.e., the cumulative effort hours of the project staff
• Number of requirements with completed specifications versus the total number of requirements
• Number of requirements defined versus the total number of estimated requirements
The sources of these data and the frequency with which the data are collected and analyzed are shown in Table 3- 1 .
30
Section 3 - Requirements Definition
Table 3-1. Objective Measures Collected During the Requirements Definition Phase
|
MEASURE |
SOURCE |
FREQUENCY (COLLECT/ANALYZE) |
|
Staff hours (total and by activity) |
Requirements definition team and managers (time accounting) |
Weekly/monthly |
|
Requirements status (percentage of completed specifications; number of requirements defined) |
Managers |
Biweekly/biweekly |
|
Estimates of total requirements, total requirements definition effort, and schedule |
Managers |
Monthly/monthly |
staff hours
completed specifications
defined requirements
Evaluation Criteria
Effort should be gauged against estimates based on historical data from past projects of a similar nature. Monitor staff hours separately for each major activity. If schedules are being met but hours are lower than expected, the team may not be working at the level of detail necessary to raise problems and issues.
To judge progress following the SCR, track the number of requirements for which specifications have been written as a percentage of the total number of requirements. ("Total require- ments" includes those for which a need has been identified, but for which details are still TBD.)
Monitor requirements growth by tracking the number of requirements that have been defined against an estimated total for the project. If requirements stability is an issue, consider tracking the number of changes made to requirements as well. Excessive growth or change to specifications point to a need for greater management control or to the lack of a detailed system operations concept.
31
Section 3 - Requirements Definition
PRODUCTS
The key products of the requirements definition phase are the system and operations concept (SOC) document and the requirements and specifications document. The content and form of these products are addressed in the following paragraphs.
System and Operations Concept Document
The SOC document lists the high-level requirements, defines the overall system architecture and its operational environment, and describes how the system will operate within this environment. The document provides a base from which developers can create the software structure and user interface. The format recommended for the document is shown in Figure 3-3.
The SOC is not usually updated after publication. During the requirements analysis phase, developers refine the reuse proposal contained in the document and publish the resulting reuse plan in the requirements analysis report. Similarly, developers refine the operational scenarios and include them in the requirements analysis, preliminary design, and detailed design reports. Because these and other pieces of the SOC are reworked and included in subsequent development products, it may not be necessary to baseline or maintain the SOC itself.
Requirements and Specifications Document
This document is produced by the requirements definition team as the key product of the requirements definition phase. It is often published in multiple volumes: volume 1 defines the requirements, volume 2 contains the functional specifications, and volume 3 provides mathematical specifications. The document is distributed prior to the SRR, updated following the review to incorporate approved review items, and then baselined.
The requirements and specifications document contains a complete list of all requirements — including low-level, derived requirements — and provides the criteria against which the software system will be acceptance tested. The functional or object specifications, which identify the input data, output data, and processing required to transform input to output for each process, provide the basis for detailed design and system testing. The document also includes the mathematical background information necessary to evaluate specified algorithms and to design the system correctly.
32
Section 3 - Requirements Definition
The recommended outline for the requirements and specifications document is presented in Figure 3-4.
SYSTEM AND OPERATIONS CONCEPT DOCUMENT
This document provides a top-down view of the system from the user's perspective by describing the behavior of the system in terms of operational methods and scenarios. Analysts should provide the document to the development team by the end of the requirements definition phase. The suggested contents are as follows:
1. Introduction
a. Purpose and background of the system
b. Document organization
2. System overview
a. Overall system concept
b. System overview with high-level diagrams showing external interfaces and data flow
c. Discussion and diagrams showing an ideal, high-level architecture for the system
3. Reuse proposal
a. Summary of domain and reuse analysis performed
b. Description of potential candidates for reuse — architectural components, designs, operational processes, and test approaches — and associated trade-offs
c. Discussion and diagrams of the proposed high-level architecture, as adjusted to incorporate reusable elements
4. Operational environment — description and high-level diagrams of the environment in which the system will be operated
a. Overview of operating scenarios
b. Description and high-level diagrams of the system configuration (hardware and software)
c. Description of the responsibilities of the operations personnel
5. Operational modes
a. Discussion of the system's modes of operation (e.g., critical versus normal and launch/early mission versus on-orbit operations)
b. Volume and frequency of data to be processed in each mode
c. Order, frequency, and type (e.g., batch or interactive) of operations in each mode
6. Operational description of each major function or object in the system
a. Description and high-level diagrams of each major operational scenario showing all input, output, and critical control sequences
b. Description of the input data, including the format and limitations of the input. Sample screens (i.e., displays, menus, popup windows) depicting the state of the function before receiving the input data should also be included.
c. Process — high-level description of how this function will work
d. Description of the output data, including the format and limitations of the output. Samples (i.e., displays, reports, screens, plots) showing the results after processing the input should also be included.
e. Description of status and prompt messages needed during processing, including guidelines for user responses to any critical messages
7. Requirements traceability matrix mapping each operational scenario to requirements
Figure 3-3. SOC Document Contents
33
Section 3 - Requirements Definition
REQUIREMENTS AND SPECIFICATIONS DOCUMENT
This document, which contains a complete description of the requirements for the software system, is the primary product of the requirements definition phase. In the flight dynamics environment, it is usually published in three volumes: volume 1 lists the requirements, volume 2 contains the functional specifications, and volume 3 provides the mathematical specifications.
1. Introduction
a. Purpose and background of the project
b. Document organization
2. System overview
a. Overall system concept
b. Expected operational environment (hardware, peripherals, etc.)
c. High-level diagrams of the system showing the external interfaces and data flows
d. Overview of high-level requirements
3. Requirements — functional, operational (interface, resource, performance, reliability, safety, security), and data requirements
a. Numbered list of high-level requirements with their respective derived requirements (derived requirements are not explicitly called out in source documents such as the SIRD or SORD, but represent constraints, limitations, or implications that must be satisfied to achieve the explicitly stated requirements)
b. For each requirement:
(1) Requirement number and name
(2) Description of the requirement
(3) Reference source for the requirement, distinguishing derived from explicit
requirements
(4) Interfaces to other major functions or external entities
(5) Performance specifications — frequency, response time, accuracy, etc.
4. Specifications
a. Discussion and diagrams showing the functional or object hierarchy of the system
b. Description and data flow/object diagrams of the basic processes in each major subsystem
c. Description of general conventions used (mathematical symbols, units of measure, etc.)
d. Description of each basic function/object, e.g.:
(1) Function number and name
(2) Input
(3) Process — detailed description of what the function should do
(4) Output
(5) Identification of candidate reusable software
(6) Acceptance criteria for verifying satisfaction of related requirements
(7) Data dictionary — indicating name of item, definition, structural composition of the
item, item range, item type
5. Mapping of specifications to requirements — also distinguishes project-unique requirements from standard requirements for the project type (AGSS, dynamics simulator, etc.)
& Mathematical specifications — formulas and algorithm descriptions to be used in implementing the computational functions of the system
a. Overview of each major algorithm
b. Detailed formulas for each major algorithm
Figure 3-4. Requirements and Specifications Document Contents
34
Section 3 - Requirements Definition
REVIEWS
Two key reviews are conducted during the requirements definition phase: the system concept review and the system requirements review. The purpose, participants, scheduling, content, and format of these reviews are discussed in the subsections that follow.
System Concept Review
The SCR gives users, customer representatives, and other interested parties an opportunity to examine and influence the proposed system architecture and operations concept before detailed requirements are written. It is held during the requirements definition phase after system and operations concepts have been defined. In the flight dynamics environment, a full SCR is conducted for large, mission support systems. For smaller development efforts without complex external interfaces, SCR material is presented informally. The SCR format is given in Figure 3-5.
SCR FORMAT Presenters — requirements definition team
Participants
• Customer representatives
• User representatives
• Representatives of systems and groups that will interface with the system to be developed
• Senior development team representatives (application specialists)
• Quality assurance (QA) representatives
• System capacity/performance analysts
Schedule — after the system and operations document is complete and before requirements definition begins
Agenda — summary of high-level requirements (e.g., from SIRD and SORD) and presentation of system and operations concepts; interactive participation and discussion should be encouraged.
Materials Distribution
• The system and operations concept document is distributed 1 to 2 weeks before the SCR.
« Hardcopy material is distributed a minimum of 3 days before SCR.
Figure 3-5. SCR Format
SCR Hardcopy Material
The hardcopy materials distributed for use at the review should correspond to the presentation viewgraphs. A suggested outline for the contents of SCR hardcopy material is presented in Figure 3-6.
35
Section 3 - Requirements Definition
HARDCOPY MATERIAL FOR THE SCR
1. Agenda — outline of review material
2. Introduction — purpose of system and background of the project
3. High-level requirements
a. Derivation of high-level requirements — identification of input (such as the SIRD and SORD) from project office, support organization, and system engineering organization
b. Summary of high-level requirements
4. System concept
a. Assumptions
b. Overall system concept
c. List of major system capabilities
5. Reuse considerations
a. Existing systems reviewed for possible reuse
b. Reuse trade-offs analyzed
c. Proposed reuse candidates
& High-level system architecture
a. Description and high-level diagrams of the proposed system architecture (hardware and software), including external interfaces and data flow
b. Diagrams showing the high-level functions of the system — their hierarchy and interaction
7. System environment
a. Computers and peripherals
b. Communications
c. Operating system limitations and other constraints
& Operations concept
a. Assumptions
b. Organizations that provide system and support input and receive system output
c. System modes of operation (e.g., critical versus normal and launch versus on-orbit operations)
d. Order, frequency, and type (e.g., batch or interactive) of operations in each mode
e. Discussion and high-level diagrams of major operational scenarios
f. Performance implications
9. Issues, TBD items, and problems — outstanding issues and TBDs and a course of action to handle them
Figure 3-6. SCR Hardcopy Material Contents
System Requirements Review (SRRI
When the requirements and specifications document is distributed, the requirements definition team conducts an SRR to present the requirements, obtain feedback, and facilitate resolution of outstanding issues. The SRR format, schedule, and participants are given in Figure 3-7.
36
Section 3 - Requirements Definition
■?-
SRR FORMAT Presenters — requirements definition team
Participants
• Customer representatives
• User representatives
• Configuration Control Board (CCB)
• Senior development team representatives
• System capacity/performance analysts
• Quality assurance representatives
Schedule — after requirements definition is complete and before the requirements analysis phase begins
Agenda — selective presentation of system requirements, highlighting operations concepts and critical issues (e.g., TBD requirements)
Materials Distribution
• The requirements and specifications document is distributed 1 to 2 weeks before SRR.
• Hardcopy material is distributed a minimum of 3 days before SRR.
Figure 3-7. SRR Format
f TAILORING NOTE "\
For very large or complex projects, hold a preliminary SRR to obtain interim feedback from users and customers. The format of the PSRR is the same as the SRR. Hardcopy material contains preliminary results and is adjusted to reflect work accomplished to date.
SRR Hardcopy Material
Much of the hardcopy material for the review can be extracted from the requirements and specifications document. An outline and suggested contents of the SRR hardcopy material are presented in Figure 3-8.
r
r
DEFINITION
1
The Configuration Control Board (CCBlis a NASA/GSFC committee that reviews, controls, and approves FDD systems, internal interfaces, and system changes. Among its duties are the approval of system baseline reviews (e.g., SRR, PDR) and baseline documents (e.g., require- ments and specifications, detailed design document).
37
Section 3 - Requirements Definition
10. 11. 12.
HARDCOPY MATERIAL FOR THE SRR
Agenda — outline of review material
Introduction — purpose of system and background of the project
Requirements summary — review of top-level {basic) requirements developed to form the specifications
a. Background of requirements — overview of project characteristics and major events
b. Derivation of requirements — identification of input from project office, support organization, and system engineering organization used to formulate the requirements: e.g., the SIRD, SORD, memoranda of information (MOIs), and memoranda of understanding (MOUs)
c. Relationship of requirements to level of support provided — typical support, critical support, and special or contingency support
d. Organizations that provide system and support input and receive system output
e. Data availability — frequency, volume, and format
f. Facilities — target computing hardware and environment characteristics
g. Requirements for computer storage, failure/recovery, operator interaction, diagnostic output, security, reliability, and safety
h. Requirements for support and test software — data simulators, test programs, and
utilities i. Overview of the requirements and specifications document — its evolution,
including draft dates and reviews and outline of contents
Interface requirements — summary of human, special-purpose hardware, and automated system interfaces, including references to interface agreement documents (IADs) and interface control documents (ICDs)
Performance requirements — system processing speed, system response time, system failure recovery time, and output data availability
Environmental considerations — special computing capabilities, e.g., graphics,
operating system limitations, computer facility operating procedures and policies, support
software limitations, database constraints, and resource limitations
Derived system requirements — list of those requirements not explicitly called out in the SIRD, SORD, MOIs, and MOUs, but representing constraints, limitations, or implications that must be satisfied to achieve the explicitly stated requirements
Operations concepts
a. High-level diagrams of operating scenarios showing intended system behavior from the user's viewpoint
b. Sample input screens and menus; sample output displays, reports, and plots; critical control sequences
Requirements management approach
a. Description of controlled documents, including scheduled updates
b. Specifications/requirements change-control procedures
c. System enhancement/maintenance procedures
Personnel organization and interfaces
Milestones and suggested development schedule
Issues, TBD items, and problems — a characterization of all outstanding requirements issues and TBDs, an assessment of their risks (including the effect on progress), and a course of action to manage them, including required effort, schedule, and cost
Figure 3-8. SRR Hardcopy Material Contents
38
Section 3 - Requirements Definition
EXTT CRITERIA
Following the SRR, the requirements definition team analyzes all RIDs, determines whether requirements changes are necessary, and revises the requirements and specifications document accordingly. The updated document is sent to the configuration control board (CCB) for approval. Once approved, it becomes a controlled document — the requirements baseline.
Use the following questions to determine whether the requirements and specifications are ready to be given to the development team for analysis:
• Do specifications exist for all requirements for which information is available? Have TBD requirements been minimized?
• Have external interfaces been adequately defined?
• Are the specifications consistent in notation, terminology, and level of functionality, and are the algorithms compatible?
• Are the requirements testable?
• Have key exit criteria been met? That is, has the requirements and specifications document been distributed, has the SRR been successfully completed, and have all SRR RIDs been answered?
When the answer to these questions is definition phase is complete.
'yes," the requirements
r
o
NOTE
\
During and following formal reviews, review item disposition forms (RIDs) are submitted by participants to identify issues requiring a written response or further action. Managers are responsible for ensuring that all RIDs are logged and answered and resulting action items are assigned and completed.
39
o
to
(D
O
3
(0
I
30
(D
\h
c
3 3
(D
3
a
CD
J I 111
in "I
.llilidi . ,M
jin 'i is
Section 4 - Requirements Analysis
CYCLE PHASES
REQUJR
mm
NTS
REQUIRE- MENTS ANALYSIS
06 SIGN
DETAILED DESIGN
IMPLEMENTATION
?«
ACp^ANCEj
ting
SECTION 4 THE REQUIREMENTS ANALYSIS PHASE
PHASE HIGHLIGHTS __. _ ,
Memammm
ENTRY CRITERIA
1 System and operations concept completed SRR completed > Requirements and specifications baselined
EXIT CRITERIA
• Requirements analysis report completed
• Software specification review (SSR) completed
• SSR RIDs resolved
M
PRODUCTS
> Requirements analysis report
■ Software development/management plan
■ Updated requirements and specifications
MEASURES
• Staff hours •TBD requirements
> Requirements questions/answers
• Requirements changes
« Estimates of system size, effort, and schedule
METHODS AND TOOLS
• Requirements walk-throughs *
• Requirements classification *
> Requirements forms
• Requirements analysis methods and CASE tools
■ Prototyping » Project library
KEY ACTIVITIES
Requirements Definition Team
• Resolve ambiguities, discrepancies, and TBDs in the specifications
• Participate in the SSR
Development Team
• Analyze and classify requirements ■ Refine the reuse proposal
• Identify technical risks
• Prepare the requirements analysis report •Conduct the SSR
Management Team
• Prepare the software development/ management plan
• Staff and train the development team
• Interact with analysts and customers to facilitate resolution of requirements issues
• Review the products of the requirements analysis process
Plan the transition to preliminary design
■ ■ hj ■ ■ ■ ■ ■ ■ _■ ■ n
muumUw
UUUUUMN
UUUlAid
TF
The guiding philosophy of the Cleanroom method is intellectual control and reliance on the human mind to build a quality product the first time. Walk-throughs and require- ments classifications help intensify scrutiny and analysis of requirements early in the life cvcle so that requirements modifications during subsequent phases are minimized.
asasssA
PRECEDING FA3E £?_ANK NOV RLMcD
41
Section 4 - Requirements Analysis
OVERVIEW
The purpose of the requirements analysis phase is to ensure that the requirements and specifications are feasible, complete, and consistent, and that they are understood by the development team.
Requirements analysis begins after the requirements definition team completes the requirements and specifications and holds the SRR. During requirements analysis, members of the development team carefully study the requirements and specifications document. They itemize and categorize each statement in the document to uncover omissions, contradictions, TBDs, and specifications that need clarification or amplification. The development team takes the analysis that was performed in the requirements definition phase to the next level of detail, using the appropriate analysis methodology for the project (e.g., structured or object-oriented analysis). When analysis is complete, the team presents its findings at an SSR.
r
(
TAILORING NOTE
1
On large projects, requirements analysis begins at the PSRR. Key members of the develop- ment team examine the review materials, participate in the review itself, and begin classifying requirements shortly thereafter.
The development team works closely with the requirements definition team during the entire phase. The requirements definition team participates in walk-throughs, answers questions, resolves requirements issues, and attends the SSR. Meanwhile, the project manager plans the approaches to be used in developing the software system and in managing the development effort, obtains and trains the necessary staff, and reviews the products produced during the phase.
Figure 4-1 is a high-level data flow diagram of the requirements analysis process.
n
0
NOTE
A typical development team comprises the project manager, who manages project resources, monitors progress, and serves as a technical consultant the project (or task) leader, who provides technical direction and daily supervision
the programmers and application specialists who perform the technical work
a quality assurance representative a project librarian (see METHODS & TOOLS)
42
Section 4 - Requirements Analysis
NOTE: The methodologies used in the requirements classification and analysis activities (processes 4.1 and 4.2 in the above DFD) are described under METHODS AND TOOLS below. The requirements analysis report (process 4.3) is discussed under PRODUCTS, and a separate subsection is devoted to the SSR (process 4.4). The planning activity (process 4.5) is outlined under MANAGEMENT ACTIVITIES and is described in detail in Section 3 of Reference 1 2.
Figure 4-1. Analyzing Requirements
43
Section 4 - Requirements Analysis
KEY ACTIVITIES
In the requirements analysis phase, activities are divided primarily among the requirements definition team, the development team, and software development managers. The key activities that each performs during the requirements analysis phase are itemized in the following subsections. Figure 4-2 is a sample timeline showing how these activities are typically scheduled.
Activities of the Requirements Definition Team
• Resolve ambiguities, discrepancies, and TBDs in the specifications. Conduct the initial walk-throughs of the requirements and specifications for the development team and participate in later walk-throughs. Respond to all developer questions.
Resolve the requirements issues raised by the development team. Incorporate approved modifications into the requirements and specifications document.
• Participate in the SSR.
Activities of the Development Team
• Analyze and classify requirements. Meet with the requirements definition team to walk through and clarify each requirement and specification. Identify requirements and specifications that are missing, conflicting, ambiguous, or infeasible. Assign a classification of mandatory, requires review, needs clarification, information only, or TBD to each item in the requirements and specifications document.
r
(
NOTE
\
See METHODS AND TOOLS below for more information about walk-throughs, requirements classifications, and analysis methodologies.
E I
Use structured or object-oriented analysis to verify the specifications. Expand the high-level diagrams in the requirements and specifications document to a lower level of detail, and supply missing diagrams so that all specifications are represented at the same level. Ensure that user interactions and major data stores (e.g., attitude history files) are completely specified.
Determine the feasibility of computer capacity and performance requirements in view of available resources. Establish initial performance estimates by comparing specified
44
Section 4 - Requirements Analysis
r
(
NOTE
\
The contents of the requirements analysis report and the software development/management plan are covered under PRODUCTS below. The SSR is discussed separately at the end of this section.
r
f REFERENCE
\
i
See the Manager's Handbook for Software Development and the Approach to Software Cost Estimation (References 12 and 18, respectively) for guidance in estimating project size, costs , and schedule.
functions/algorithms with those of existing systems. Use the estimates to model overall performance (CPU, I/O, etc.) for the operational scenarios described in the SOC. Adjust the SOC scenarios to take these results into account.
Walk through the results of classification and analysis with the requirements definition team.
Refine the reuse proposal into a realistic plan. Analyze the software reuse proposal in the SOC in light of the existing software's current operational capabilities and any changes to the requirements baseline.
Identify areas of technical risk. Plan and conduct prototyping efforts or other appropriate techniques to minimize these risks.
Prepare the requirements analysis report and
distribute it before the SSR.
Conduct the SSR and resolve all RIDs.
Activities of the Management Team
• Prepare the software development/management plan (SDMP). Review the histories of related, past projects for applicable size, cost, and schedule data as well as lessons learned. Determine what resources are needed, develop a staffing profile, and estimate project costs. Identify project risks and plan to minimize them. Document the technical and management approaches that will be used on the project.
• Staff and train the development team. Bring staff onto the project as soon as possible following SRR (or, on large projects, PSRR). Ensure communications among development team members, managers, and the requirements definition team.
Also make certain that the requirements definition team is adequately staffed following SRR, so that TBD and changing requirements can be given prompt and thorough analysis.
• Interact with analysts and customers to facilitate resolution of requirements issues. Work with team leaders to assess the
45
Section 4 - Requirements Analysis
REQUIREMENTS
DEFINITION
TEAM
SOFTWARE
DEVELOPMENT
TEAM
MANAGEMENT TEAM
_y
Conduct requirements walk-throughs
Participate in walk-throughs
Answer developer questions
Incorporate changes to requirements
Participate in SSR
_y
Participate in walk-throughs
Submit questions
Classify requirements
Generate DFDs/OO diagrams
Conduct analysis walk-throughs
Identify risks; conduct prototyping efforts; refine operational scenarios
Refine the reuse proposal
Produce the requirements analysis report
-^
Prepare and conduct the SSR
Resolve RIDs
zr
Estimate resources and schedules; staff the development team
2W
Facilitate resolution of requirements issues; review products
Prepare the SDMP
Direct the SSR
_V
Plan the transition to preliminary design
SRR
SSR
TIME
Figure 4-2: Timeline of Key Activities in the Requirements Analysis Phase
feasibility of proposed requirements changes and to estimate their impact on costs and schedules.
Review the products of the requirements analysis process. Look at requirements classifications, data-flow or object-oriented diagrams, the data dictionary, the requirements analysis report, and the SSR hardcopy materials. Schedule the SSR and ensure participation from the appropriate groups.
Plan an orderly transition to the preliminary design phase. Convey to the development team members the parts of the software development plan that apply to preliminary design (e.g., design standards and configuration management procedures) and instruct them in the specific software engineering approach to use during design. While the key team members are preparing for SSR, have the remainder of the development team begin preliminary design activities.
46
Section 4 - Requirements Analysis
METHODS AND TOOLS
The following methods, techniques, and tools are used to support the activities of the requirements analysis phase:
Requirements walk-throughs
Requirements classifications
Requirements forms
Structured and object-oriented requirements analysis
CASE tools
Prototyping
The project library
Each is discussed below. Requirements Walk-Throughs
At the beginning of the requirements analysis phase, developers meet informally with analysts of the requirements definition team to go through the requirements and specifications. During these initial walk-throughs, analysts discuss each of the specifications, explain why certain algorithms were selected over others, and give developers the opportunity to raise questions and issues.
After developers have analyzed and classified the requirements and specifications, they conduct walk-throughs of their results for the requirements definition team. One walk-through should be held for each major function or object in the system. During these later walk-throughs, both teams review all problematic specification items and discuss any needed changes to the requirements and specifications document.
To ensure that all problem areas and decisions are documented, one member of the development team should record the minutes of the walk-through meeting. Developers will need the minutes to fill out requirements question-and-answer forms for any issues that require confirmation, further analysis, or other action by the requirements definition team.
Requirements Classification
When the development team is thoroughly familiar with the requirements and specifications document, they take each passage (sentence or paragraph) in the requirements and specifications document and classify it as either mandatory, requires review, needs clarification, information only, or TBD.
41
Section 4 - Requirements Analysis
An item is mandatory if it is explicitly defined in project-level requirements documents such as the SIRD or SORD, or if it has been derived from analysis of the project-level requirements. If mandatory items are removed from the specifications, the system will fail to meet project-level requirements.
If (on the basis of project-level requirements and the system and operations concept) there is no apparent need for a particular requirement or specification, then that item requires review (i.e., further analysis by the requirements definition team). The item must be deleted from the specification (by means of a specification modification) or moved into the mandatory category before CDR.
An item needs clarification when it is ambiguous, appears infeasible, or contradicts one or more of the other requirements or specifications.
An item is labelled as information only if it contains no requirement or specification per se. Such an item may provide background information, helpful hints for the software developer, etc.
A requirement or specification item is TBD if (1) the item contains a statement such as "the process is TBD at this time," or (2) information associated with the item is missing or undefined.
[HINT
19
1
If the requirements and specifications are available in a database, enter the classifications and supporting commentary into the database online. Otherwise, summarize each requirement or specification item, create a list of the summaries, and use the lists to assign classifications.
Requirements Forms
During the requirements analysis and subsequent phases, question- and-answer forms are used to communicate and record requirements issues and clarifications. Specification modifications are used to document requirements changes.
The development team uses question-and-answer forms to track questions submitted to the requirements definition team and to verify their assumptions about requirements. Managers of the requirements definition team use the forms to assign personnel and due dates for their team's response to developers. Responses to questions submitted on the forms must be in writing.
The question-and-answer form cannot be used to authorize changes to requirements or specifications. If analysis of the submitted
question-and- answer forms
48
Section 4 - Requirements Analysis
question or issue reveals that a requirements change is needed,
.„ . members of the requirements definition team draft a specification
speatica ion modification. Proposed specification modifications must be
approved by the managers of both the requirements definition and the development teams and by the CCB. The requirements definition team incorporates all approved specification modifications into the requirements and specifications document.
Analysis Methods and CASE Tools
The methods and tools applicable for requirements analysis are the same as those recommended for the requirements definition phase in Section 3. The development team will generally use the same method as was used by the requirements definition team to take the analysis down to a level of detail below that provided in the specifications. This allows the development team to verify the previous analysis and to fill in any gaps that may exist in the document. If CASE tools were used in the requirements definition phase to generate data flow or object diagrams, it is important to use the same tools in the requirements analysis phase. The value of a CASE tool as a productivity and communication aid is greatly reduced if developers must re-enter or reformat the diagrams for a different tool.
If the requirements definition team has used functional decomposition for their analysis and the development team needs to generate an object-oriented design, then extra analysis steps are required. The development team must diagram the details of the specification at a low level, then use the diagrams to abstract back up to higher-level requirements. This allows the team to take a fresh, object-oriented look at the system architecture and to restructure it as needed.
Prototyping
During the requirements analysis phase, prototyping activities are usually conducted to reduce risk. If unfamiliar technology (e.g., hardware or new development language features) will be employed on the project, prototyping allows the development team to assess the feasibility of the technology early in the life cycle when changes are less costly to effect. If system performance or reliability is a major, unresolved issue, the team can prototype critical operations or algorithms.
On projects where the requirements for the user interface must be prototyped — either because the interface is critical to system success or because users are uncertain of their needs — a tool that
49
Section 4 - Requirements Analysis
allows the developer to set up screens and windows rapidly is often essential. With such a tool, the developer can give the user the "look and feel" of a system without extensive programming and can obtain early feedback. The tool should be able to generate menus, multiple screens, and windows and respond to input. One such tool that has been successfully used in the SEL is Dan Bricklin's Demo Program.
r
(
RULE
1
Caution must be exercised to ensure that any prototyping activity that is conducted is necessary, has a defined goal, and is not being used as a means to circumvent standard development procedures. See PRODUCTS in Section 4 for additional guidance on how to plan a prototyping effort.
Project Library
In each software development project, one team member is assigned the role of librarian. During a project, the librarian (sometimes called the software configuration manager) maintains the project library, which is a repository of all project information. The librarian also maintains configured software libraries and operates various software tools in support of project activities.
The librarian establishes the project library during the requirements analysis phase. In general, the project library contains any written material used or produced by the development team for the purpose of recording decisions or communicating information. It includes such items as the requirements and specifications document, requirements question-and-answer forms, approved specification modifications, and the requirements analysis summary report. Necessary management information, such as the software development/management plan, is also included.
the librarian
MEASURES
The following paragraphs describe the measures and evaluation criteria that managers can use to assess the development process during the requirements analysis phase.
Objective Measures
The progress and quality of requirements analysis are monitored by examining several objective measures:
• Staff hours — actual, cumulative hours of staff effort, as a total and per activity
• Requirements questions and answers — the number of question- and-answer forms submitted versus the number answered
50
Section 4 - Requirements Analysis
Table 4-1. Objective Measures Collected During the Requirements Analysis Phase
MEASURE
Staff hours (total and by activity)
Requirements (changes and additions to baseline)
Requirements (TBD specifications)
Requirements (Questions/answers)
Estimates of total SLOC, total effort, schedule, and reuse
SOURCE
Developers and managers (via Personnel Resources Forms (PRFs))
Managers
(via Development
Status Forms (DSFs))
Managers Managers (via DSFs)
Managers (via Project Estimates Forms (PEFs))
FREQUENCY {COLLECT/ANALYZE)
Weekly/monthly
Biweekly/biweekly
Biweekly/biweekly Biweekly/biweekly Monthly/monthly
DATA COU-ECTION
CONTINUED
BEGUN
/
NOTE
\
' The SEL uni 3 hardcopy forms to collect metrics during the requirements analysis phase. The Personnel Resources Form is used by the development team to record weekly effort hours. The Project Estimates Form is used by managers to record their monthly size and effort estimates. The Development Status Form is used to record the number of requirements changes, and number of requirements questions vs. answers. See Reference 19 for detailed information about SEL data collection forms and procedures.
• TBD requirements — the number of requirements classified as TBD versus the total number of requirements
• Requirements changes — the total cumulative number of requirements for which specification modifications have been approved
• Estimates of system size, reuse, effort, and schedule — the total estimated number of lines of code in the system; the estimated number of new, modified, and reused (verbatim) lines of code; the total estimated staff hours needed to develop the system; and estimated dates for the start and end of each phase of the life cycle.
For each of these measures, Table 4-1 shows who provides the data, the frequency with which the data are collected and analyzed, and whether data collection is continued from the requirements definition phase or newly initiated.
51
Section 4 - Requirements Analysis
Evaluation Criteria
Staff hours are usually graphed against a profile of estimated staff effort that is generated by the software development manager for the SDMP (Figure 4-5). This early comparison of planned versus actual staffing is used to evaluate the viability of the plan.
In the flight dynamics environment, hours that are lower than expected are a serious danger signal — even if schedules are being met — because they indicate the development team is understaffed. If too few developers perform requirements analysis, the team will not gain the depth of understanding necessary to surface requirements problems. These problems will show up later in the life cycle when they are far more costly to rectify.
A growing gap between the number of questions submitted and the number of responses received or a large number of requirements changes may indicate problems with the clarity, correctness, or completeness of the requirements as presented in the requirements and specifications document. Data from similar past projects should be used to assess the meaning of the relative sizes of these numbers.
Because unresolved TBD requirements can necessitate severe design changes later in the project, the number of TBD requirements is the most important measure to be examined during this phase. Categorize and track TBD requirements according to their severity. TBD requirements concerning external interfaces are the most critical, especially if they involve system input. TBDs affecting internal algorithms are generally not so serious.
A TBD requirement is considered severe if it could affect the functional design of one or more subsystems or of the high-level data structures needed to support the data processing algorithms. Preliminary design should not proceed until all severe TBD requirements have been resolved. A TBD requirement is considered nominal if it affects a portion of a subsystem involving more than one component. Preliminary design can proceed unless large numbers of nominal TBD requirements exist in one functional area. An incidental TBD requirement is one that affects only the internals of one unit. Incidental TBD requirements should be resolved by the end of detailed design.
staff hours
requirements questions and changes
TBD requirements
For each TBD requirement, estimate the effect on system size, required effort, cost, and schedule. Often the information necessary to resolve a TBD requirement is not available until later, and design must begin to meet fixed deadlines. These estimates will help determine the uncertainty of the development schedule.
MORE MEASURES
\
Consider tracking these additional measures of progress during the require- ments analysis phase:
• number of requirements classified vs. total requirements
• number of requirements diagrams completed vs. estimated total diagrams
52
Section 4 - Requirements Analysis
Explanation: The original staffing plan was based on an underestimate of the system size. Toward the end of the design phase, 40% more effort was required on a regular basis. This was one of many Indicators that the system had grown, and the project was replanned accordingly. However effort continued to grow when the second plan called for it to level off and decline. When it was clear that Mil more staff would be required to maintain progress, an audit was conducted. The audit revealed that the project was plagued with an unusually large number of unresolved TBDs and requirements changes that were causing an excessive amount of rework and that - as pan of the corrective action - another replan was necessary.
Figure 4-3. Effort Data Example — ERBS AGSS
system size estimates
NOTE
The growth of system size estimates is another key indicator of project stability. Estimating the final size of the system is the first step in the procedure for determining costs, schedules, and staffing levels (Section 3 of Reference 12). Make the initial estimate by comparing current requirements with information from past projects within the application environment. Update and plot the estimate each month throughout the life cycle.
\
In comparing actual data (e.g., staff hours) versus estimates, the amount of deviation can show the degree that the development process or product is varying from what was expected, or it can indicate that the original plan was in error. If the plan was in error, then updated planning data (i.e., estimates) must be produced.
As the project matures, the degree of change in the estimates should stabilize. If requirements growth pushes the system size estimate beyond expected limits, it may be necessary to implement stricter change control procedures or to obtain additional funding and revise project plans. See Section 6 of Reference 12 for additional guidance in evaluating size estimates.
53
Section 4 - Requirements Analysis
PRODUCTS
The following key products are produced during this phase:
• The requirements analysis report
• The software development/management plan
• Updated requirements and specifications document
• Prototyping plans (as needed)
These products are addressed in the paragraphs that follow. The Requirements Analysis Report
The requirements analysis report establishes a basis for beginning preliminary design and is, therefore, a key product of the requirements analysis phase. This report includes the following:
• The updated reuse plan (The original reuse proposal was developed during the requirements definition phase and recorded in the systems and operations concept document. It is adjusted to reflect approved requirements changes and the results of analysis of the reusable software's current capabilities.)
• Updates to operational scenarios (in view of prototyping results, performance analyses, requirements changes, and functional reallocations)
• The DFDs or object-oriented diagrams generated to analyze and complete the specifications
• A summary of the results of requirements analysis, highlighting problematic and TBD requirements, system constraints, and development assumptions
• An analysis of the technical risks of the project, as well as cost and schedule risks resulting from TBD requirements or other factors
Figure 4-4 presents the format and contents of the requirements analysis report.
The Software Development/Management Plan
The SDMP provides a detailed exposition of the specific technical and management approaches to be used on the project. In the SDMP, the development team manager discusses how the recommended approach will be tailored for the current project and provides the resource and schedule estimates that will serve as a baseline for comparisons with actual progress data.
54
Section 4 - Requirements Analysis
REQUIREMENTS ANALYSIS REPORT
This report is prepared by the development team at the conclusion of the requirements analysis phase. It summarizes the results of requirements analysis and establishes a basis for beginning preliminary design. The suggested contents are as follows:
1. Introduction — purpose and background of the project, overall system concepts, and document overview
2. Reuse proposal — key reuse candidates and overall architectural concept for the system
3. Operations overview — updates to system and operations concepts resulting from work performed during the requirements analysis phase
a. Updated operations scenarios
b. Operational modes, including volume and frequency of data to be processed in each mode, order, and type of operations, etc.
c. Updated descriptions of input, output, and messages
4. Specification analysis .
a. Summary of classifications (mandatory, requires review, information only, needs clarification, or TBD) assigned to requirements and specifications
b. Problematic specifications — identification and discussion of conflicting, ambiguous, infeasible, untestable, and TBD requirements and specifications
c. Unresolved requirements/operations issues, including the dates by which resolutions are needed
d. Analysis of mathematical algorithms
5. System constraints
a. Hardware availability — execution, storage, peripherals
b. Operating system limitations
c. Support software limitations
6. Performance estimates and models
7. Development assumptions
a Risks, to both costs and schedules. (These should include risks related to TBD or changing requirements, as well as technical risks.)
9. Prototyping efforts needed to resolve technical risks, including the goals and completion criteria for each prototyping effort
10. Data flow or object-oriented diagrams — results of all structured or object-oriented analysis of the requirements performed during the requirements analysis phase
11. Data dictionary — for the updated processes, data flows, and objects shown in the diagrams
Figure 4-4. Requirements Analysis Report Contents
The manager prepares the SDMP during the requirements analysis phase and keeps it up to date throughout the development life cycle. Because of the primary importance of this plan, it is described in detail in the Manager's Handbook for Software Development (Reference 12).
55
Section 4 - Requirements Analysis
The SDMP includes a software development approach; a description of risks and risk mitigation; an initial estimate of the system's size; and estimates of the schedule, staffing, resources, and cost of the project. Figure 4-5 outlines the contents of the SDMP.
SOFTWARE DEVELOPMENT/MANAGEMENT PLAN
In some sections of the plan, material (shown in italics) is to be regularly added during the life of the project. Other sections should be revised and reissued if circumstances require significant changes in approach.
1. INTRODUCTION
1.1 Purpose — brief statement of the project's purpose.
1.2 Background — brief description that shows where the software products produced by the project fit into the overall system.
1.3 Organization and Responsibilities
1 .3.1 Project Personnel — explanation and diagram of how the development team will organize activities and personnel to carry out the project: types and numbers of personnel assigned, reporting relationships, and team members' authorities and responsibilities (see Reference 12 for guidelines on team composition).
1.3.2 Interfacing Groups — list of interfacing groups, points of contact, and group responsibilities.
2. STATEMENT OF PROBLEM — brief elaboration of the key requirements, the steps (numbered) to be taken to accomplish the project, and the relation (if any) to other projects.
3. TECHNICAL APPROACH
3.1 Reuse Strategy — high-level description of the current plan for reusing software from • existing systems.
32 Assumptions and Constraints —that govern the manner in which the work will be performed.
33 Anticipated and Unresolved Problems —that may affect the work and the expected effect on each phase.
34 Development Environment — development computer and programming languages.
35 Activities, Tools, and Products — for each phase, a matrix showing (a) the major activities to be performed, (b) the development methodologies and tools to be applied, and (c) the products of the phase. Includes discussion of any unique approaches or activities.
3£ Build Strategy — which portions of the system will be implemented in which builds
and the rationale for this. Determined during the preliminary design phase. Updated at the end of detailed design and after each build.
Figure 4-5. SDMP Contents (1 of 2)
s«
56
Section 4 - Requirements Analysis
MANAGEMENT APPROACH
4.1
42
43
44
45
Assumptions and Constraints — that affect the management approach,
including project priorities.
Resource Requirements — tabular lists of estimated levels of resources required,
including estimates of system size (new and reused SLOC), staff effort (managerial,
programmer, and support) by phase, training requirements, and computer resources.
Includes estimation methods or rationale used. Updated estimates are added at the
end of each phase.
Milestones and Schedules — list of work to be done, who will do it, and when it
will be completed. Includes development life cycle (phase start and finish dates);
build/release dates; delivery dates of required external interfaces; schedule for
integration of externally developed software and hardware; list of data, information,
documents, software, hardware, and support to be supplied by external sources and
delivery dates; list of data, information, documents, software, and support to be
delivered to the customer and delivery dates; and schedule for reviews (internal
and external). Updated schedules are added at the end of each phase.
Measures — a table showing, by phase, which measures will be collected to capture
project data for historical analysis and which will be used by management to
monitor progress and product quality (see Reference 12). If standard measures will
be collected, references to the relevant standards and procedures will suffice.
Describes any measures or data collection methods unique to the project.
Risk Management — statements of each technical and managerial risk or
concern and how it is to be mitigated. Updated at the end of each phase to
incorporate any new concerns.
5. PRODUCT ASSURANCE
5.1 Assumptions and Constraints — that affect the type and degree of quality control and configuration management to be used.
52 Quality Assurance — table of the methods and standards that will be used to ensure the quality of the development process and products (by phase). Where these do not deviate from published methods and standards, the table should reference the appropriate documentation. Methods of ensuring or promoting quality that are innovative or unique to the project are described explicitly. Identifies the person(s) responsible for quality assurance on the project, and defines his/her functions and products by phase.
53 Configuration Management — table showing products controlled, as well as tools and procedures used to ensure the integrity of the system configuration (when is the system under control, how are changes requested, who makes the changes, etc.). Unique procedures are discussed in detail. If standard configuration management practices are to be applied, references to the appropriate documents are sufficient. Identifies the person responsible for configuration management and describes this role. Updated before the beginning of each new phase with detailed configuration management procedures for the phase, including naming conventions, directory designations, reuse libraries, etc.
a APPENDIX: PROTOTYPING PLANS — collected plans for each prototyping effort to be conducted on the project.
7. PLAN UPDATE HISTORY — lead sheets from each update of the SDMP, indicating which sections were updated and when the update was made.
Figure 4-5. SDMP Contents (2 of 2)
57
Section 4 - Requirements Analysis
Updated Requirements and Specifications
During this phase, the requirements definition team prepares updates to the requirements and specifications document on the basis of approved specification modifications. Additional specification modifications may be approved as a result of discussion at the SSR or the RID process. The requirements definition team must ensure that the updated requirements and specifications document is republished shortly after the SSR, so that it will be available to the developers as they generate the software design.
Prototyping Plans
Managing a prototype effort requires special vigilance. Progress is often difficult to predict and measure. A prototyping effort may continue indefinitely if no criteria are established for evaluating the prototype and judging completion. Writing a plan for each prototyping activity, no matter how brief, is vital to establishing control.
The length of the plan and the time to prepare it should be proportional to the size and scope of the prototyping effort. A one- page plan may be all that is required for small prototyping efforts. A brief plan need not be published separately but may, instead, be incorporated into the SDMP (Figure 4-5).
The following items should be included in the plan:
• Objective of the prototype — its purpose and use
• Statement of the work to be done and the products to be generated
• Completion criteria
• Assessment methods — who will evaluate the prototype and how it will be evaluated
• Technical approach
• Resources required — effort and size estimates, staff, hardware, software, etc.
• Schedule
The SDMP should contain summaries of the detailed prototyping plans. Each summary should describe the general approach, discuss the items to be prototyped, include effort estimates, provide a schedule, and discuss the rationale for the schedule.
58
Section 4 - Requirements Analysis
SOFTWARE SPECIFICATION REVIEW
At the conclusion of requirements analysis, the development team holds an SSR. This is a high-level review conducted for project management and the end users of the system. The SSR format, schedule, and participants are itemized in Figure 4-6.
SSR FORMAT Presenters — software development team
Participants
■ Requirements definition team
• Customer interfaces for both the requirements definition and software development teams
• User representatives
• Representatives of interfacing systems
• Quality assurance representatives for both teams
• System capacity/performance analysts •CCB
Schedule — after requirements analysis is complete and before the preliminary design phase is begun
Agenda — selective presentation of the results of requirements analysis, directed primarily toward project management and the users of the system
Materials Distribution
• The requirements analysis report and software development/ management plan are distributed 1 to 2 weeks before SSR.
• Hardcopy material is distributed a minimum of 3 days before SSR.
Figure 4-6. SSR Format
SSR Hardcopy Material
The hardcopy materials for the review will contain some of the same information found in the requirements analysis report. Keep in mind that there is some flexibility in selecting the most appropriate information to include in the presentation. The contents suggested in Figure 4-7 are intended as a guideline.
59
Section 4 - Requirements Analysis
HARDCOPY MATERIAL FOR THE SSR
1. Agenda — outline of review material
2. Introduction — background of the project and purpose of system
3L Analysis overview — analysis approach, degree of innovation required in analysis, special studies, and results
4. Revisions since SRR — changes to system and operations concepts, requirements, and specifications effected following the SRR
5. Reusable software summary
a. Key reuse candidates — identification of existing software components that satisfy specific system specifications exactly or that will satisfy the specifications
after modification
b. Overall architectural concept for the system
c. Matrix of requirements to be fulfilled by reused components
& Requirements classification summary
a. List of requirements and specifications with their assigned classifications (mandatory, requires review, needs clarification, information only, or TBD)
b. Problematic specifications — identification and discussion of conflicting, ambiguous, infeasible, and untestable requirements and specifications
c. Unresolved requirements/operations issues, including the dates by which resolutions to TBDs are needed (NOTE: This is a key element of the SSR.)
7. Functional or object-oriented specifications
a. Object diagrams or high-level data flow diagrams showing input, transforming processes, and output
b. Data set definitions for external interfaces to the system
a Performance model — key estimates and results of modeling system performance
9. Development considerations
a. System constraints — hardware availability, operating system limitations, and support software limitations
b. Utility, support, and test programs — list of auxiliary software required to support development (e.g., data simulators, special test programs, software tools, etc.)
c. Testing requirements
d. Development assumptions
10. Risks, both to costs and schedules — includes how risks are identified, their potential impact, and how they will be managed. Covers risks related to TBD or changing requirements as well as technical risks
11. Summary of planned prototyping efforts needed to resolve technical risks, including
the goals and schedule for each effort and a summary of any prototyping conducted to date
12. Key contacts — leaders of technical teams, application specialists, and other key project members
13. Milestones and schedules — includes size estimates, development life cycle (phase start and finish dates), schedule for reviews (internal and external), build/release requirements, delivery dates of required external interfaces, schedule for integration of externally developed software and hardware
Figure 4-7. SSR Hardcopy Material
60
Section 4 - Requirements Analysis
EXIT CRITERIA
To determine whether the development team is ready to proceed with preliminary design, consider the following questions:
• Have all TBD requirements been identified and their impacts assessed?
• Are performance requirements (e.g., timing, memory, and accuracy) clear? Are the requirements feasible, given the environmental constraints? Are sufficient computer resources available?
• Have the key exit criteria for the phase been met? That is, has the requirements analysis report been distributed, has the SSR been successfully completed, and have all SSR RIDs been answered?
When these criteria have been met, the requirements analysis phase is complete.
61
On
W
(D
30
CD
lis
CD
3
(D
3 r* (/>
>
a m
V)
ill iiiiii II
Mil I ml I
jm ««
Section 5 - Preliminary Design
CYCLE PHASES
|
REQUIREMENTS DEFINITION |
REQUIRE- MENTS ANALYSIS |
PRELIMI- NARY DESIGN |
msp |
IMPLEMENTATION |
?M |
*m«P |
SECTION 5
THE PREUMINARY DESIGN PHASE
PHASE HIGHLIGHTS
c
^i^;g5ijs^sgs*^
PRODUCTS
• Preliminary design report
$&mistm^wm#3mBmi&mwmsi$^&m;m8!Sz
MEASURES
• Units identified/designed
• Requirements Q&As, TBDs, and changes
• Staff hours
• Estimates of system size, effort, schedule, and reuse
jgms8smwxwz»»}w,M^^>^3w>mww?»}^)m<m&s&
METHODS AND TOOLS
Functional decomposition and object-oriented design ** Prologs and PDL Software engineering notebooks Design walk-throughs*** Design inspections*** Reuse verification Analysis methods
EXIT CRITERIA
Preliminary design report generated PDR completed PDR RIDs answered
ima^gffliaMigMasmMiiiMSS
KEY ACTIVITIES
| Development Team*
• Prepare preliminary design diagrams
• Prepare prologs and PDL for high-level functions/objects
• Document the design in the preliminary design report
•Conduct the PDR
'xTO'xgwH'A'a^jym-xWxg:':'
Management Team
• Reassess schedules, staffing, training, and other resources
• Plan, coordinate, and control requirements changes
• Control the quality of the preliminary design process and products
• Plan the transition to detailed design
Requirements Definition Team
• Resolve outstanding requirements issues
• Participate in design walk-throughs and PDR
I
m»M»:i.m»:
warnm*
With the Cleanroom methodology:
* All test activities are conducted by a separate test team established at the beginning of preliminary design. During this phase, the test team develops a usage profile for statistical testing, derives a list of functions to be tested, and drafts a preliminary system test plan.
Box structures (References 20,21) are used to develop the design and examine alternatives. •••Cleanroom relies upon design walk-throughs for understanding and upon inspections for ensuring quality products. Both methods have been used extensively on SEL-monitored projects and are key elements of the SEL's recommended approach.
PRECEDING P3GE rWNK not pimQ
63
Section 5 - Preliminary Design
OVERVIEW
The purpose of the preliminary design phase is to define the high- level software architecture that will best satisfy the requirements and specifications for the system.
During preliminary design, the development team uses the updated requirements and specifications document to develop alternative designs and to select an optimum approach. The team partitions the system into major subsystems, specifies all system and subsystem interfaces, and documents the design using structure charts or annotated design diagrams. Developers use an iterative design process that proceeds somewhat differently, depending on whether a functional decomposition or object-oriented design approach is chosen.
Early in this phase, developers examine the software components that are candidates for reuse and verify their compatibility with overall system requirements and the emerging design. Prototyping activities begun during the requirements analysis phase may continue and new prototyping efforts may be initiated. Developers also define error-handling and recovery strategies, determine user inputs and displays, and update operational scenarios.
During this phase, the development team continues to work closely with analysts of the requirements definition team to resolve requirements ambiguities and TBDs. To ensure that the emerging design meets the system's requirements, developers send formal requirements questions to analysts for clarification, conduct walk- throughs, and subject all design products to peer inspection.
The preliminary design phase culminates in the preliminary design review (PDR), during which developers present the rationale for selecting the high-level system design. The preliminary design report documents the initial system design and is distributed for review prior to the PDR.
Figure 5-1 presents a high-level data flow diagram of the preliminary design process.
f TAILORING NOTE ^
On projects with a high degree of reuse, the preliminary and detailed design phases may be combined. In that case, both preliminary and detailed design activities are conducted, but developers hold only a CDR and produce only the detailed design report.
64
Section 5 - Preliminary Design
REQUIREMENTS ANALYSIS REPORT
UPDATED REQUIREMENTS AND SPECIFICATIONS DOCUMENT
R HARDCOPY MATERIALS
NOTE: The processes labelled 5.1, 5.2, and 5.3 are described in the KEY ACTIVITIES subsection. Prologs and POL (5.3) and design methodologies (5.2) are also discussed under METHODS AND TOOLS. The PDR is described under REVIEWS, and the preliminary design document is covered in PRODUCTS.
Figure 5-1. Developing the Preliminary Design
65
Section 5 - Preliminary Design
KEY ACTIVITIES
The following are the key activities of the development team, the management team, and the requirements definition team during the preliminary design phase. The development team performs the principal activities of the phase. The requirements definition team concentrates on resolving outstanding TBD requirements and providing support to the development team. The relationships among the major activities of these groups are shown in Figure 5-2.
Activities of the Development Team
• Prepare preliminary design diagrams. Using functional decomposition or object-oriented techniques, expand the preliminary software architecture that was proposed in earlier phases. Idealize the expanded architecture to minimize features that could make the software difficult to implement, test, maintain, or reuse.
Evaluate design options. Weigh choices according to system priorities (e.g., optimized performance, ease of use, reuse considerations, reliability, or maintainability). Use prototyping and performance modeling to test alternatives, especially in risk areas.
Examine the software components that are candidates for reuse. If system response requirements are especially stringent, model the performance of the reusable components. Update the reuse plan to reflect the results of these reuse verification activities.
Generate high-level diagrams of the selected system design and walk the analysts of the requirements definition team through them. Use the high-level design diagrams to explain the system process flow from the analyst's perspective. Focus on system and subsystem interfaces. Explain refinements to the operations scenarios arising from analysis activities and include preliminary versions of user screen and report formats in the walk- through materials.
r
(
TAILORING NOTE
\
1
Design diagrams, prologs, and PDL are required for all systems, regardless of the design methodology applied. METHODS AND TOOLS discusses ways these items are represented.
r
0
NOTE
\
Reuse verification encompasses designs, documentation, and test plans and data as well as code. See METHODS AND TOOLS for more details.
66
Section 5 - Preliminary Design
REQUIREMENTS
DEFINITION
TEAM
SOFTWARE
DEVELOPMENT
TEAM
MANAGEMENT TEAM
Answer developer questions; resolve requirements issues, TBDs
Participate in design wa I k-th roughs
Participate in PDR
Develop idealized design
Evaluate design alternatives; prototype risk areas
Conduct reuse trade-off analyses
Prepare preliminary design diagrams
Refine operational scenarios
. 3?
Conduct design walk-throughs
Prepare prologs, PDL
Prepare preliminary design report
Conduct design inspections
Prepare and conduct PDR Resolve PDR RIDs
_37
Record project history data; reassess schedules, staffing, resources
Plan and control requirements changes; control quality
Update SDMP estimates
Plan the transition to detailed design
Direct the PDR
^
SSR
PDR
■TIME"
Figure 5-2. Preliminary Design Phase Timeline
67
Section 5 - Preliminary Design
Prepare prologs and PDL for the high-level functions/objects. For FORTRAN systems, prepare prologs and PDL to one level below the subsystem drivers. For Ada systems, prepare and compile specifications for the principal objects in the system and construct sufficient PDL to show the dependencies among packages and subprograms. (See Figure 5-4.)
Provide completed design diagrams, unit prologs/package specifications, and PDL to other members of the development team for independent inspection and certification.
• Document the selected design in the preliminary design report. Include the reuse plan, alternative design decisions, and external interfaces.
• Conduct the PDR and resolve RIDs. Record design changes for use in the detailed design phase, but do not update the preliminary design report.
Activities of the Management Team
During preliminary design, the manager's focus changes from planning to control. The following are the major management activities of this phase:
• Reassess schedules, staffing, training, and other resources. Begin the software development history by recording lessons learned and project statistics from the requirements analysis phase. Include percentages of project effort and schedule consumed, growth of system size estimates, and team composition.
r
(
NOTE
\
Contents of the preliminary design report and PDR materials are provided under the PRODUCTS and REVIEW headings, respectively, in this section. Inspection and certification procedures are covered under METHODS AND TOOLS.
r
(
NOTE
\
Material for the software development history (SDH) is collected by the management team throughout the life of the project. See Section 9 for an outline of SDH contents.
Ensure that the development team contains a mix of software engineers and personnel experienced in the application area. If the project is large, partition the development team into groups, usually by subsystem, and appoint group leaders. Adjust staffing levels to compensate for changes in requirements and staff attrition, and ensure the team obtains the training it needs to meet specific project demands.
68
Section 5 - Preliminary Design
• Plan, coordinate, and control requirements changes. Interface with analysts and the customer to facilitate resolution of requirements issues and TBDs. Monitor the number and severity of requirements questions submitted to analysts and the timeliness of responses. Ensure that analysts and the customer know the dates by which TBDs need to be resolved and understand the impact of changing or undetermined requirements items.
Assess the technical impact and cost of each specification modification. Constrain modifications that necessitate extensive rework and non-critical enhancements.
• Control the quality of the preliminary design process and its products during day-to-day management activities. Ensure that design walk-throughs, inspections, and reviews are scheduled and conducted. Attend walk-throughs and, optionally, inspections and oversee the reporting, tracking, and resolution of the design issues that arise. Make certain that all requisite software documentation is generated and review the preliminary design document. Ensure that the team adheres to project standards and configuration management procedures.
• Plan an orderly transition to the detailed design phase.
Consider the impacts of TBDs, specification modifications, and schedule or team adjustments. Revise project estimates of effort, duration, and size and update corresponding sections of the SDMP. Develop the project build strategy and prepare a preliminary build plan reflecting prototyping results, project risks, and remaining TBDs.
Increase team size if necessary to begin detailed design and address the training needs of additional personnel. Oversee the establishment of online libraries to store unit prologs, PDL, and reused code. While project and group leaders prepare for PDR, start the rest of the team on detailed design activities.
Control the PDR and ensure that all exit criteria have been met before declaring the phase complete.
Activities of the Requirements Definition Team
During the preliminary design phase, the requirements definition team provides support to software developers through the following activities:
69
Section 5 - Preliminary Design
Continue to resolve requirements issues and TBDs. Clarify ambiguous, conflicting, or incomplete requirements. Provide prompt, written replies to developers' requirements questions and discuss these responses with developers. Respond to changes in high-level system requirements, evaluate the impact of each change, and prepare specification modifications accordingly.
Participate in design walk-throughs and the PDR.
Thoroughly analyze the proposed design. Work with developers to refine the operational scenarios and preliminary user interface. Follow up with developers to address issues raised during the walk-throughs.
Review the preliminary design report and all supporting hardcopy materials before PDR. Pose questions and provide critiques of the initial, high-level system design during the review meeting, and use RIDs to document serious discrepancies.
METHODS AND TOOLS
The primary methods and tools used during the preliminary design phase are
• Functional decomposition and object-oriented design
• Prologs and PDL
• Software engineering notebooks (SENs)
• Design walk-throughs
• Design inspections
• Reuse verification
• Analysis methods: prototyping, performance modeling, and code analysis
Functional Decomposition and Object- Oriented Design
Design technologies are methods by which software developers define the major components of a software system, describe the interrelationships among components, and create a foundation for implementation. Design diagrams, structure charts, and documentation support these methods. Through these tools, developers demonstrate that a chosen design approach incorporates
r
0
NOTE
\
During the design and implemen- tation phases, the software development and requirements definition teams continue to use question-and-answer forms and specification modifications to record and resolve requirements issues. See METHODS AND TOOLS, Section 4, for more details.
70
Section 5 - Preliminary Design
r
f REFERENCE
( REFERENCE
DD
A thorough discussion of object-orianted analysis and design is provided in References 11, 16, and 17.
Structured design principles (Reference 13) form the basis of the functional decomposition method used in the SEL.
each capability and interface specified in the requirements and specifications document. The two principal design technologies used on SEL-monitored projects are functional decomposition and object-oriented design (OOD).
When using afunctional decomposition design method, developers identify the major functions of a system and successively refine them into smaller and smaller functionally oriented components. High levels in the design define the algorithmic abstraction (the "what" of the process), and the lower levels provide primitive operations that implement the higher level actions.
In the flight dynamics environment, functional decomposition is normally used for the development of FORTRAN systems. When using this design approach, functional baseline diagrams (tree charts) are generated during preliminary design for all components to two levels below the subsystem drivers (as shown in Figure 5-3). The remaining design diagrams (levels 3 to N) are completed during detailed design. Separate structure charts may augment the diagrams; alternatively, interface information may be added directly to the tree charts.
r
f REFERENCE
\
DQ
Cohesion and coupling, indicators of software system strength, reliability, and maintainability, are discussed in Reference 13.
The SEL also recommends that functionally oriented designs employ the principles of information hiding, data abstraction, loose coupling, and cohesion. Components below the heavy line in the functional decomposition hierarchy of Figure 5-3 denote low-level routines or utilities whose details are deferred to the detailed design phase. However, developers must still understand the total system architecture to produce a correct preliminary design.
When using an object-oriented approach, designers identify the abstract objects and their attributes that model the real-world system, define operations on those objects, and establish the interfaces between them. By focusing primarily on the objects (the "things" of the system) rather than on the actions that affect those objects, object-oriented techniques
71
Section 5 - Preliminary Design
f
tf
MAIN EXECUTIVE
SYSTEM LEVEL
SUBSYSTEM
LEVEL
SUBSYSTEM LEVEL 1
SUBSYSTEM LEVEL 2
(LEVELTBETowTTH!sTlNt"AHENar" ADDRESSED UNTIL DETAILED DESIGN)
SUBSYSTEM
LEVEL 3
PRELIMINARY DESIGN DETAILED DESIGN
SUBSYSTEM LEVEL N
Figure 5-3. Extent of the Design Produced for FORTRAN Systems During the Preliminary and Detailed Design Phases
allow designers to map their solutions more directly to the problem.
In the flight dynamics environment, Ada is typically the language involved when OOD techniques are chosen. In the preliminary design of Ada systems, all packages and subprograms that address elements of the problem domain are identified. This includes all high-level objects necessary to implement the system capabilities, the functions and procedures affecting these objects, externally visible data, and all interfaces and dependencies.
72
Section 5 - Preliminary Design
Developers use object-oriented, stepwise refinement until all subsystems, all packages, and all visible subprograms within those packages have been identified. Design of package bodies (the hidden elements shaded in Figure 5-4) is reserved until the detailed design phase. A generalized preliminary design diagram appropriate for an Ada system is shown in Figure 5-4.
PACKAGE
r ■
GENERIC | PACKAGE
IMWKtiiiiJfflMmSffli
PACKAGE
AU^UimM
PACKAGE
PACKAGE
wwimimmm
PACKAGE
PACKAGE
/
NOTE: The shaded elements of this figure represent hidden portions that are not specified until the detailed design phase.
\
/
\
SUB- PROGRAM
/
\
PACKAGE
VISIBLE PART
SPECIFICATION
.HIDDEN PART
Figure 5-4. Level of Detail Produced for Ada Systems During Preliminary Design
73
Section 5 - Preliminary Design
Prologs and PDL
Comparable to the blueprint in hardware systems, prologs and PDL communicate the concept of the design to the level of detail necessary for implementation. The prolog provides a textual explanation of the unit's purpose and variables; PDL provides a formal, algorithmic specification for the unit. By using prologs and PDL, the developer is able to communicate the exact intent of the design to reviewers and coders..
The SEL views the use of prologs and PDL during design as beneficial and cost-effective. Regardless of the design methodology chosen, developers are required to generate unit prologs and high-level PDL (consisting of such items as call dependencies, major logic branches, and error-handling strategies) to complete the preliminary design.
r
(
REFERENCE
\
M
SEL conventions for prologs and PDL are found in References 22 (Ada conventions) and 23 (FORTRAN conventions).
TAILORING NOTE
\
For large Ada systems with broad, flat designs, creating PDL for externally visible elements of all packages and all visible subprograms entails extensive effort. When this situation exists, software managers should adjust effort and schedule allocations to allow sufficient time to complete this work in preliminary design.
For FORTRAN systems, prologs and PDL are produced to one level below the subsystem drivers. For object-oriented systems, package specifications (which serve as prologs in Ada systems) and high-level PDL are generated for all program elements depicted in the design diagrams (see Figure 5-4). To identify interface errors, Ada PDL is always compiled; developers use templates and a language-sensitive editor (LSE) to standardize PDL structure.
Software Engineering Notebooks
A software engineering notebook (SEN) is a workbook (i.e., a file folder or special notebook) that facilitates quality assurance and configuration management by consolidating printed information pertinent to a software component. This information becomes more detailed as the life cycle progresses. When printed documentation is combined with online source files in later phases, the SEN provides a baseline history of an element's evolution through the development process.
During preliminary design, developers initiate SENs at a subsystem or logical function level. Into these SENs they collect notes documenting design decisions, design diagrams, structure charts, and signed design inspection checklists for the subsystem or function. SENs are usually maintained by developers until after unit testing, when they are turned over to the project librarian.
74
Section 5 - Preliminary Design
Design Walk-Throughs
Developers conduct design walk-throughs to ensure that both the requirements definition and development teams understand the system design as it takes shape. Developers distribute materials prior to the walk-through to participants, who include other developers, analysts, user representatives, representatives of systems that will interface with the software under development, and managers. During the meeting, developers carefully explain how operational aspects of the system (processing sequences and interfaces, screen formats, and user inputs) are reflected in the emerging design. Participants comment on how completely and accurately developers have interpreted the system requirements. A recording secretary notes discrepancies, errors, and inconsistencies and records action items. If significant issues remain at the end of the walk-through, a follow-up session may be scheduled.
The initial walk-through typically presents the overall, system level approach and is later followed by walk-throughs of subsystems and their major parts. When a project is large and the development team has been partitioned into groups, it is important that the group leader of any subsystem that interfaces with the subsystem being presented attend the session.
rr
f
NOTE
\
Design inspections are conducted during both the preliminary and detailed design phases because different units are designed in each phase, ff a unit design was inspected and certified during the preliminary design phase, it is not re- inspected during the detailed design phase unless it has been revised. See METHODS AND TOOLS in Section 6 for a detailed description of design inspection procedures.
Design Inspections
Whereas design walk-throughs focus on explaining operational aspects of the system design, design inspections are independent, in- depth, technical reviews of the design diagrams, prologs, and PDL that are performed by software team peers. Inspections are held as logically related parts of the system design become clear and complete; they are scheduled when unit prologs and PDL have been generated to the required level. Developers distribute these materials for study by the inspection team prior to holding a working meeting.
An inspection team consists of three or more members of the development team who are versed in the project's standards, development language, and system requirements. One member of the team acts as the moderator for the meeting.
75
Section 5 - Preliminary Design
Inspection team participants certify that unit logic and interfaces
accurately represent the system requirements and that developers
have applied correct design principles. Reviewers document their
assessment and note weaknesses or interface conflicts on design design
inspection checklists (Figure 6-3). The signed checklist also inspection
certifies that the unit follows prescribed project standards and checklists
conventions.
Reuse Verification
Reuse verification is the process of determining which of the existing software components specified in the reuse proposal should be integrated into the new system design. During reuse verification, developers examine code and documentation from sources such as the FDFs Reusable Software Library (RSL). Developers draw on their experience in considering the integrity of the overall system architecture, the clarity of the design, and system performance.
When the reuse plan recommends using large portions of existing systems, developers must assess the trade-offs of compromising an optimum system design to make it compatible with existing software. They must consider long-term impacts on total software development costs, design clarity, performance requirements, system size, maintainability, and reliability when weighing design options.
When factors (such as incompatible language versions or a high incidence of operating system-specific calls) prohibit an existing component from being reused, developers can study the software and its documentation to understand its function, organization, and data structures before designing a component compatible with the new system. Thus, reused experience is shared across projects even when explicit design and code cannot be.
Analysis Methods: Prototyping, Performance Modeling, and Code Analysis
During preliminary design, the development team uses prototyping to validate design concepts and to test the trade-offs of design options. Developers compose prototype drivers (or scaffolding code) to exercise components planned for reuse in the new system. They also prototype user screens and report formats. To confirm that existing components will meet the new system's performance requirements, developers couple prototyping with performance and source code analysis, as described below.
76
Section 5 - Preliminary Design
Performance modeling is a means of predicting how efficiently a program will use resources on a given computer. To generate these predictions, developers use such parameters as the number of units anticipated, the volume and frequency of the data flow, memory usage estimates, and the amount of program I/O. Analogy with existing, similar systems may also be used. Results of performance modeling assist developers in deciding among design options.
If executable code exists (e.g., scaffolding code or reused units), developers can run performance analyzers, such as Problem Program Evaluator (PPE) or the VAX Performance and Coverage Analyzer, concurrently with the code. These dynamic analyzers generate information such as CPU time, I/O counts, and page fault data that help developers identify areas of the code (e.g., inefficient loop structures or calculations) that need to be redesigned.
Static code analyzers (e.g., VAX Source Code Analyzer) are tools that read the source code of existing components and generate information describing their control structure, symbol definitions, and variable occurrences. A developer can examine the call trees produced by a static code analyzer to assess the scope of a proposed change to a reusable component's interfaces. The designer can then decide which approach is better — to modify and test all affected units or to design a new component.
MEASURES
During preliminary design, managers continue to use the objective measures of the requirements analysis phase. They also begin to monitor additional progress data. The following measures are collected:
• The number of units designed versus the number identified
• Requirements questions and answers, TBDs, and changes
• Staff hours
• Estimates of system size, effort, schedule, and reuse
The source of these data and the frequency of data collection and evaluation are shown in Table 5- 1 .
Evaluation Criteria
units designed
Project leaders estimate the number of units that will be needed to represent the preliminary system design. Against this estimate, they track the number of unit designs (prolog and PDL) that have been generated and the number certified. Management plots assist in
77
Section 5 - Preliminary Design
Table 5-1. Objective Measures Collected During the Preliminary Design Phase
|
MEASURE |
SOURCE |
FREQUENCY (COLLECT/ANALYZE) |
DATA COLLECTION |
|
|
CONTINUED |
BEGUN |
|||
|
Staff hours (total and by activity) |
Developers and managers (via PRFs) |
Weekly/monthly |
* |
|
|
Requirements (changes and additions to baseline) |
Managers (via Development Status Forms (DSFs)) |
Biweekly/biweekly |
* |
|
|
Requirements (TBD specifications) |
Managers (via DSFs) |
Biweekly/biweekly |
* |
|
|
Requirements (questions/answers) |
Managers (via DSFs) |
Biweekly/biweekly |
* |
|
|
Estimates of total SLOC (new, modified, reused), total units, total effort, and schedule |
Managers (via PEFs) |
Monthly/monthly |
* |
* (total units) |
|
Status (units planned/ designed/ certified) |
Managers (via DSFs) |
Biweekly/biweekly |
• |
r
c
RULE
discovering trends or plateaus in this progress data that signal impending difficulties. The graph of units certified should closely follow and parallel the graph for units designed in a fairly smooth curve. Sharp increases (a "stair- step" graph) will appear when many units are hurriedly certified together in an effort to meet schedules.
During preliminary design, a widening gap between the number of requirements questions submitted and the number of answers received can be an early warning signal of impending v
rework and eventual schedule slippage. A high number of questions and answers when compared with systems of similar size and complexity is interpreted the same way.
Tracking the number of TBD requirements that persist into the preliminary design phase, especially those concerning external interfaces and hardware changes, is crucial because TBDs represent
\
The number of units designed should not be used as a measure of unit completion. The correct completion measure is the number of certified unit designs.
requirements questions and answers
TBD requirements
78
Section 5 - Preliminary Design
requirements changes
r
(
NOTE
A
Numbers of Q&As, TBDs, and specification modifications can change rapidly. Plots of these factors help managers to assess project status and highlight problem areas.
incompleteness in the design and increase the potential for rework. TBDs should diminish quickly in the early life cycle phases.
Specification modifications may be issued in response to development team questions or external project influences such as hardware changes. The number and severity of specification modifications resulting from developers' questions reflect the quality of the requirements and specifications document. These changes are normally addressed by the development and requirements definition teams. The number and severity of specification modifications from external causes have more far-reaching implications and should alert managers to anticipate long-term perturbations in schedule and effort estimates.
staff hours
r
(
NOTE
\
SEL managers update effort, schedule, and size estimates approximately once a month and organize these estimates on the Project Estimates Form (PEF). Data from these forms are used to generate system growth and progress plots.
estimates
r
(
NOTE
\
Although a number of measures of design quality (strength, etc.) have been proposed, the SEL has not yet found objective measures that provide significant insight into the quality of a design.
Significant deviations between planned and actual staff effort hours warrant close examination. When a high level of effort is required to meet schedules, the development team's productivity may be low or the problem may be more complex than originally realized. Low staff hours may indicate delayed staffing on the project or insufficient requirements analysis. The effects of these last conditions are not always immediately obvious in preliminary design, but will surface dramatically as design deficiencies during subsequent phases.
Managers can now use the number of units planned and average unit size to refine estimates of system size. The number of reused units in the system also becomes firmer; managers identify units to be reused without change versus those to be modified and revise effort and schedule projections accordingly.
Estimates are a key management measure; widely varying estimates or sharp increases always warrant investigation. In the preliminary design phase, excessive growth in system size estimates is generally seen when requirements are unstable or change control mechanisms are ineffective.
79
Section 5 - Preliminary Design
PRODUCTS
The primary product of the preliminary design phase is the high- level design of the system, as documented in the preliminary design report. The report incorporates the results of reuse verification and prototyping and forms the basis for the detailed design document. Because of their size, unit prologs and PDL are normally published in a separate volume that is identified as an addendum to the report.
An oudine of the preliminary design report, showing format and content, is provided as Figure 5-5.
PRELIMINARY DESIGN REVIEW
The phase concludes with the preliminary design review (PDR), during which the development team presents the high-level system design and the rationale for choosing that design over alternatives. Also highlighted in the PDR are explanations of external system interfaces, revisions to operations scenarios, major TBDs for resolution, and issues affecting project quality and schedule.
Materials presented at PDR do not necessarily convey the technical depth that the development team has achieved during preliminary design; details of this technical effort are documented in the preliminary design report. Developers limit the PDR presentation to the nominal operating scenarios and significant contingency cases.
The presentation is directed to project managers, users, the requirements definition team, and the CCB. Applications specialists, analysts, quality assurance personnel, and managers perform a detailed technical review of the preliminary design material prior to attending the formal review. They evaluate the system design and provide comments and critiques to the development team during and immediately after the presentation. RIDs are used by participants to record any issues that still need to be resolved. The PDR format and schedule are shown in Figure 5-6, followed by an outline of the PDR hardcopy materials (Figure 5-7).
80
Section 5 - Preliminary Design
PRELIMINARY DESIGN REPORT
This report is prepared by the development team as the primary product of the preliminary design phase. It presents the high-level design of the system and forms the basis for the detailed design document. The suggested contents are as follows:
1. Introduction — purpose and background of the project, overall system concepts, and document overview
2. Design overview
a. Design drivers and their order of importance (e.g., performance, reliability, hardware, memory considerations, operating system limitations, language considerations, etc.)
b. Results of reuse tradeoff analyses; the reuse strategy
c. Critique of alternative designs
d. Discussion and high-level diagrams of the selected system design, showing hardware interfaces, external data interfaces, interconnections among subsystems, and data flow
e. A traceability matrix of the subsystems against the requirements
f. Design status
(1) List of constraints, concerns, and problem areas and their effects on the design
(2) List of assumptions and possible effects on design if they are wrong List of TBD requirements and an assessment of their effect on system size, required effort, cost, and schedule ICD status Status of prototyping efforts
(3)
(4) (5)
g. Development environment (i.e., hardware, peripheral devices, etc.)
Operations overview
a. Operations scenarios/scripts (one for each major product that is generated). Includes the form and volume of the product and the frequency of generation. Panels and displays should be annotated to show what various selections will do and should be traced to a subsystem
b. System performance considerations
c. Error recovery strategies (automatic fail-over, user intervention, etc.)
Design description for each subsystem or major functional breakdown:
a. Discussion and high-level diagrams of subsystem, including interfaces, data flow, and communications for each processing mode
b. High-level description of input and output
c. High-level description of processing keyed to operator-specified input and actions in terms of points of control, functions performed, and results obtained (both normal and abnormal, i.e., error processing and recovery)
d. Structure charts or object-oriented diagrams expanded to two levels below the subsystem driver
e. Prologs (specifying the unit's purpose, operation, calling sequence arguments, external references, etc.) and program design language (PDL) for each identified unit (Prologs and PDL are normally published in a separate volume.)
Data interfaces for each internal and external interface:
a. Description, including name, function, frequency, coordinates, units, and computer type, length, and representation
b. Format
(1) Organization, access method, and description of files (i.e., data files, tape, etc.)
(2) Layout of frames, samples, records, and/or message blocks
(3) Storage requirements
Figure 5-5. Preliminary Design Report Contents
81
Section 5 - Preliminary Design
PDR FORMAT
Presenters — software development team
Participants
• Requirements definition team
• Quality assurance representatives from both teams
• Customer interfaces for both teams
• User representatives
• Representatives of interfacing systems
• System capacity/performance analysts •CCB
Schedule — after the preliminary design is complete and before the detailed design phase begins
Agenda — selective presentation of the preliminary design of the system
Materials Distribution
•The preliminary design report is distributed at least 1 week before PDR.
• Hardcopy material is distributed a minimum of 3 days before PDR.
Figure 5-6. PDR Format
EXTTCRTTERIA
To determine whether the development team is ready to proceed with detailed design, managers should ask the following questions:
• Have all components that are candidates for reuse been analyzed? Have the trade-offs between reuse and new development been carefully investigated?
• Have developers evaluated alternate design approaches and chosen the optimum design?
• Have all design diagrams, prologs and PDL (or package specifications, if applicable) been generated to the prescribed level? Have they been inspected and certified?
• Have the key exit criteria been met? That is, has the preliminary design report been produced and distributed, has the PDR been successfully completed, and have all PDR RIDs been answered?
When the manager can answer "yes" to each of these questions, the preliminary design phase is complete.
82
Section 5 - Preliminary Design
HARDCOPY MATERIAL FOR THE PDR
1. Agenda — outline of review material
2. Introduction — background of the project and system objectives
3. Design overview
a. Design drivers and their order of importance {e.g., performance, reliability, hardware, memory considerations, programming language, etc.)
b. Results of reuse tradeoff analyses (at the level of subsystems and major components)
c. Changes to the reuse proposal since the SSR
d. Critique of design alternatives
e. Diagram of selected system design. Shows products generated, interconnections among subsystems, external interfaces. Differences between the system to be developed and existing, similar systems should be emphasized
f. Mapping of external interfaces to ICDs and ICD status
4. System operation
a. Operations scenarios/scripts — one for each major product that is generated. Includes the form of the product and the frequency of generation. Panels and displays should be annotated to show what various selections will do and should be traced to a subsystem
b. System performance considerations
c. Error recovery strategies
5. Major software components — one diagram per subsystem
6. Requirements traceability matrix mapping requirements to subsystems
7. Testing strategy
a. How test data are to be obtained
b. Drivers/simulators to be built
c. Special considerations for Ada testing
& Design team assessment — technical risks and issues/problems internal to the software development effort; areas remaining to be prototyped
9. Software development/management plan — brief overview of how the development effort is conducted and managed
10. Software size estimates — one slide
11. Milestones and schedules — one slide
12. Issues, problems, TBD items beyond the control of the development team
a. Review of TBDs from SSR
b. Other issues
c. Dates by which TBDs/issues must be resolved
Figure 5-7. PDR Hardcopy Material
83
mill i 1 1 i , m i in i i i« iiini t w m ii * i ■" ■
UiU I llll ill .dl llll III I
oo
to
a
o
3
I
■o
to
3 0)
O
CD
S"
3
* > « imnil! «■ nil
II! mi ■ *
Section 6 - Detailed Design
UFE
CYCLE
PHASES
REQUIREMENTS DEFINITION
ACQUIRE- MENTS ANALYSIS
PRELIMI- NARY DESIGN
DETAILED DESIGN
IMft-EMENTATJON
SYSTEM TESTING
ACCEPTANCE TESTING
SECTION 6 THE DETAILED DESIGN PHASE
m%>%^m$mz. *5x&
ENTRY CRITERIA
mi nary design report generated
completed
RIDs answered
EXIT CRITERIA
• Detailed design document generated
• CDR completed* •CDR RIDs answered
&J88&aaea%^^
m
PRODUCTS
• Detailed design document
• Build plan*
• Build/release test plan*
I
MEASURES
• Units designed/identified
• Requirements Q&As, TBDs, and changes
• Staff hours
• Estimates of system size, effort, schedule, and reuse
•CPU hours
METHODS AND TOOLS
• Functional decomposition and object-oriented design
• Reuse verification •Analysis methods
• Design walk-throughs
• Design inspections
• Prologs and PDL ■SENs
KEY ACTIVITIES
Development Team
• Prepare detailed design diagrams
• Conduct design walk-throughs
• Refine the operational scenarios
• Complete prologs and PDL for all units
• Provide input to the build plan and begin the build/release test plan*
• Prepare the detailed design document •Conduct the CDR
Management Team
• Assess lessons learned from the preliminary design phase
• Control requirements changes
• Control the. quality of the design process .
• Prepare the build plan
• Coordinate the transition to implementation
• Direct the CDR
Requirements Definition Team
• Resolve remaining requirements issues
• Participate in design walk-throughs and CDR
Acceptance Test Team
• Begin work on the acceptance test plan
• Prepare portions of analytical test plan needed for Build 1
f' •v---- -v 'WW
wzm
*On projects using the Cleanroom methodology, each build consists of a detailed design phase followed by an implementation phase. Statistically selected tests are planned and performed by a separate test team, which compiles, integrates, and tests each build as soon as it has passed coding inspection. An informal review is conducted after the design phase in each build.
M*MWrtHmi>M&ttHiliwiaili^
HMMMMtMAUiMMM
85
PRECEDING PilGE BLANK NOT RIMED
Section 6 - Detailed Design
OVERVIEW
The purpose of the detailed design phase is to produce a completed design specification that will satisfy all requirements for the system and that can be directly implemented in code.
Unless comments expressed at the PDR indicate serious problems or deficiencies with the preliminary design, detailed design begins following the PDR. The detailed design process is an extension of the activities begun during preliminary design. The development team elaborates the system architecture defined in the preliminary design to the unit level, producing a complete set of code -to specifications. The primary product of the phase is the detailed design document, which contains the design diagrams, prologs, and PDL for the software system.
During this phase, the development team conducts walk-throughs of the design for the requirements definition team and subjects each design specification to peer inspection. At the conclusion of the phase, the completed design is formally reviewed at the CDR.
Figure 6-1 shows the major processes of the detailed design phase.
KEYACTTVTTIES
While the development team is generating the detailed design, the requirements definition team continues to resolve the remaining requirements issues and TBDs. As soon as requirements questions and changes level off, an additional team is formed to prepare for acceptance testing. This acceptance test team usually consists of the analysts who will use the system, along with some of the staff who prepared the requirements and specifications document.
The activities of the development team, the management team, the requirements definition team, and the acceptance test team are itemized below. A suggested timeline for the performance of these activities is given in Figure 6-2.
Activities of the Development Team
• Prepare detailed design diagrams to the lowest level of detail, i.e., the subroutine/subprogram level. Successively refine each subsystem until every component performs a single function and can be coded as a single unit.
86
Section 6 - Detailed Design
Figure 6- 1. Generating the Detailed Design
Conduct design walk-throughs. Walk through each major function or object with other developers and the requirements definition team. On small projects (e.g., simulators), conduct one walk-through per subsystem. On systems of 150 KSLOC or more (e.g., AGSSs), hold two walk-throughs per subsystem — one in the early stages of detailed design and one later in the phase.
Refine the operations scenarios for the system in light of the results of prototyping, performance modeling, and design activities. Finish specifying detailed input and output formats for each subsystem, including displays, printer and plotter output, and data stores.
87
Section 6 - Detailed Design
REQUIREMENTS
DEFINITION
TEAM
SOFTWARE
DEVELOPMENT
TEAM
ACCEPTANCE
TEST
TEAM
MANAGEMENT TEAM
Answer developer questions; resolve requirements issues, TBDs
Participate in design walk-th roughs
^^
Participate in CDR
Complete all prototyping Refine operational scenarios
Finalize design diagrams
Conduct design walk-throughs
_37
Prepare all prologs and PDL Conduct design inspections
Prepare detailed design report
NOTE: Dashed lines indicate that the'activity is intermittent
Prepare build test plan
Prepare and conduct CDR ^ Resolve CDR RIDs
Begin to prepare the acceptance test plan
Plan analytical tests for Build 1
Record project history data, reassess schedules, staffing, resources
Plan and control requirements changes; control quality
Prepare build plan
Update SDMP estimates
Direct the CDR
Coordinate the transition to implementation
FOR
COR
-TIME"
Figure 6-2. Timeline of Key Activities in the Detailed Design Phase
88
Section 6 - Detailed Design
Complete all prototyping efforts. The detailed design presented at CDR should contain no uncertainties that could have been resolved through prototyping.
• Complete prologs and PDL for all units. Generate prologs and PDL for the new units specified in the design diagrams. On Ada projects, package specifications and PDL should also be compiled. This means that package bodies are compiled, and that, at a minimum, subprogram bodies each contain a null statement.
Identify all units (from the RSL or other sources) that will be reused, either verbatim or with modifications. Transfer existing units that require modification into online libraries, and revise the prologs and PDL of these units as necessary.
Ensure that all unit designs are formally inspected and certified (see Methods and Tools belowj. File the completed checklist in the SEN for the unit.
• Provide input to the build plan and begin the build test plan.
Provide the technical information needed for the build plan to the management team; include the order in which units should be implemented and integrated. Prepare the test plan for the first build and review it at CDR. (See Section 7 for the plan's format and contents.)
• Prepare the detailed design document as a basis for the CDR. Ensure that the team librarian adds all documentation produced during the phase to the project library. (The only exceptions are SEN materials, which are maintained by individual developers until the unit has been coded and tested.)
• Conduct the CDR and respond to all CDR RIDs.
Activities of the Management Team
With a few exceptions, the activities of the management team during the detailed design phase parallel those of the previous phase.
• Assess lessons learned from the preliminary design phase
and record information for the software development history, including schedule data and project statistics. Reassess schedule, staffing, and resources in view of these data.
• Control requirements changes. Continue to monitor the number and scope of requirements questions and answers.
89
Section 6 - Detailed Design
Ensure that analysts and the customer understand the potential impact of each requirement TBD and proposed specification modification.
• Control the quality of the detailed design process and its products. Ensure adherence to design standards, configuration management procedures (especially change control), reporting procedures, data collection procedures, and quality assurance procedures. Review the design produced and participate in design walk-throughs.
Ensure that all facets of the project are completely visible and that there is close cooperation between the development team and the other groups with which they must interact.
• Prepare the build plan. Use unit dependency information provided by the technical leads and application specialists of the development team to specify the portions of the system that will be developed in each stage of the implementation phase. Document the capabilities to be included in each build and prepare a detailed milestone schedule, factoring in external constraints and user needs.
• Coordinate the transition to the implementation phase. It is
usually necessary to increase the size of the development team to simultaneously implement multiple subsystems within a build. Inform the development team of the software engineering approaches to be used during implementation and provide the necessary training. Ensure that members of the development team understand the code and testing standards, and the quality assurance and configuration management procedures to be followed.
Ensure that online project libraries are established, that strict change-control procedures concerning these libraries are followed, and that the necessary software for building and testing the system is made available so that developers can begin implementation immediately after the CDR.
• Direct the CDR. Schedule and participate in the review, and ensure that all pertinent groups take part.
Activities of the Requirements Definition Team
• Resolve any outstanding requirements issues and TBDs, preparing specification modifications as necessary. Warn developers of any impending changes to requirements so that
90
Section 6 - Detailed Design
they can plan design activities accordingly. Respond to developers' questions.
• Participate in design walk-throughs and the CDR. Review the detailed design document before CDR. During the review, provide a critique of the design. Use RIDs to document issues and discrepancies.
Activities of the Acceptance Test Team
• Begin work on the acceptance test plan (Section 8) as soon as requirements have stabilized. Requirements can be considered as stable when developers are no longer submitting new requirements questions and the number of TBDs has declined to a low level.
• Prepare the portions of the analytical test plan that are needed for Build 1 (see Section 7). Meet with the development team to determine which analytical tests will be needed during the first build of the implementation phase, and complete those portions of the analytical test plan.
METHODS AND TOOLS
The same methods and tools used during the preliminary design phase continue in use during detailed design:
• Functional decomposition and object-oriented design (OOD)
• Reuse verification
• Analysis methods: prototyping, performance modeling, and code analysis
• Design walk-throughs
• Design inspections
• Prologs and PDL
• SENs
During the detailed design phase, the development team uses functional decomposition or OOD techniques to take the design diagrams down to the lowest level of detail (see Figures 5-3 and 5-4). Prototyping and performance modeling efforts that were undertaken to address design issues are completed. The team also completes its examination of the code and documentation of reusable components to determine whether each unit can be incorporated into the system as planned.
91
Section 6 - Detailed Design
The other methods and tools that continue in use from the preliminary design phase — design walk-throughs, design inspections, prologs and PDL, and SENs — have new aspects or applications that are introduced during detailed design. discussed in the paragraphs that follow.
These are
r
r
^TAILORING NOTE ^
Design Walk-throughs
During the detailed design phase, one or two design walk-throughs are held for each subsystem. Participants include members of the development team, the requirements definition team, representatives of systems that will interface with the software under development, and managers. At these walk- throughs, members of the development team step through the subsystem's design, explaining its algorithms, interfaces, and operational aspects. Participants examine and question the design at a detailed level to uncover such issues as mis-matched interfaces, contradictions between algorithms, or potential performance problems.
The design of the user interface is specifically addressed in one or more additional walk-- throughs. These sessions are attended by the future users of the system and concentrate on the users' point of view. The users learn how the system will look to them under representative operational scenarios, give feedback to developers, and provide a "reality check" on the updated requirements and specifications. Problems encountered with the specifications are documented on question-and-answer forms and submitted to the requirements definition team for action.
Design Inspections
Design inspections are the key methodology of the detailed design phase. Because the CDR is conducted primarily for the benefit of management and users, a detailed, component-by-component review of the design takes place only during design inspections. It is during these inspections that each separate design product is examined for correctness, completeness, and comprehensibility.
\
Design walk-throughs and inspections are initiated during the preliminary design phase. Section 5 defines both inspections and walk-throughs and explains the differences between the two methods.
Separate, formalized design walk-throughs are not always held on small tool development efforts. On these projects, walk-throughs may be combined with design reviews. The reviews are generally informal, since the products being examined will not be put under CCB control, and focus on system operabiiity and the user interface.
92
c ■ -2~-
Section 6 - Detailed Design
Design inspections are always conducted, regardless of the size or type of the project.
At a minimum, the inspection team consists of the moderator, the design's author, and another member of the development team. Units that require detailed knowledge of the application (such as the physics of flight dynamics) are inspected by the development team's application specialist.
On large projects, two or more of the author's peers will inspect the design and a representative from the quality assurance office may be included. Leaders of teams that are developing subsystems that interface with the components being inspected should also attend.
Each inspection session covers a set of logically related units (5 to 10 on average), for which design diagrams and unit-level PDL and prologs have been completed. Copies of the materials to be inspected are distributed to members of the inspection team several days before the session.
r
c
RULE
~Y
Every unit is important to the developing system and each new or modified unit must be reviewed with equal thoroughness. Neglecting a unit because it is reused software, it is not part of a "critical" thread, or its functions are "trivial" can be disastrous.
Each member individually reviews the materials for technical content and adherence to design standards, and comes to the inspection session prepared to comment on any flaws he or she has uncovered. The moderator records the errors, resolves disagreement, and determines whether reinspection is necessary. The author answers questions and takes action items to resolve the flaws that are identified. All participants are responsible both for finding errors and for ensuring that designs are traceable to requirements.
Design inspection checklists, such as the one shown in Figure 6-3, are distributed to reviewers with the inspection materials to remind them of key review criteria. A master checklist is compiled by the moderator and is used to certify the unit when inspection is complete.
Compiled Prologs and PDL
During the detailed design phase of an Ada project, the development team generates and compiles all PDL for the system. For this work, and for the code and test activities of subsequent phases, developers in the STL use sets of tools and utilities that are part of an Ada software development environment.
93
Section 6 - Detailed Design
UNIT DESIGN INSPECTION CHECKLIST
Unit Name
Task Number
Inspection Moderator.
_System_
.Build/Release
Jnitial Inspection Date.
KEY INSPECTION QUESTIONS
1. Does the design present a technically valid way of achieving the unit's assigned function?
2. Is all data required by the unit available and defined?
3. Is the dependency between each input and output argument and the processing apparent in the design?
4. Is it clear from the design where the outputs from the unit are generated?
5. Is the dependency between each external reference (e.g., unit file, record) and the processing apparent in the design?
6. Does the design include the necessary error detection and recovery logic7
7. Is the design, as written, sufficient to handle the upper and lower bounds associated with unit inputs (especially arguments)?
ADDITIONAL INSPECTION QUESTIONS
8. Are the prolog and PDL consistent with the unit's design diagram?
9. Does the PDL define logic as opposed to code?
10. Does the prolog contain enough information to describe the unit clearly to the unfamiliar reader?
11. Do both the prolog and PDL conform to applicable standards?
ACTION ITEMS AND COMMENTS
(List on a separate sheet. Refer to questions above by number.)
INSPECTION RESULTS
1. If all answers to 1-11 were "Yes, " the unit's design passes. Check here and sign below. I J
2. If there are serious deficiencies in the design (e.g., if more than one key question was answered "No") the author must correct the unit design and the moderator must schedule a reinspection. Scheduled date for reinspection:.
Yes No Corrected
3.
If there are minor deficiencies in the design, the author must correct the unit design and hold a followup meeting with the moderator. Scheduled date for followup meeting: .
Moderator's signature certifies that this unit meets all applicable standards and satisfies its requirements, and that any identified deficiencies have been resolved (applicable at initial inspection, followup meeting, or reinspection).
Moderator signature:.
Date.
Figure 6-3. Checklist for a Unit Design Inspection
94
Section 6 - Detailed Design
1
f DEFINITION
In Ada, the term program library refers not to a library of programs, but to a library of compilation units that comprise on* or mora programs. To detect consistency errors before an entire program is constructed, the Ada compiler cross-checks information from separately compiled units. The program library is the mechanism by which the compiler retains the information needed to perform these checks efficiently.
The Ada development environment provides a program library manager that functions as the user interface to the Ada compiler and the linker. The program library manager keeps track of which compilation units are in the library, when they were compiled, which ones have been made obsolete by more recent compilations, and the dependencies among units.
The development environment also includes a
language-sensitive editor (LSE). The LSE provides a template for the Ada language that allows developers to enter and edit prologs and PDL interactively.
Ada developers use an additional tool to expedite the generation of package bodies. This utility reads a "bare-bones" package specification, enhances it to conform to local Ada styles (see Reference 22), and uses the specification to build templates for the package body and subprograms.
The other components of the Ada development environment are used primarily during the implementation phase of the life cycle and are described in Section 7.
r
(
DEFINITION
1
r
Throughout this document, the term "module" is used to denote a collection of logically related units. In the flight dynamics environment, a module usually consists of 5 to 10 units.
f TAILORING NOTE ^
On Ada projects, one SEN is used to store documentation for each package. That is, the current listings, inspection checklists, and relevant design diagrams for the package's specification, body, and subprograms are maintained together in a single notebook.
Software Engineering Notebooks (SENs)
By the end of the detailed design phase, the development team's librarian will have created a SEN for each unit and/or module in the system. The developer uses the SEN to store all documentation that pertains to a unit, including the current listing of the unit's prolog and PDL, the unit design inspection checklist, design diagrams, and notes documenting design decisions. Through unit code, test, and integration, each developer retains the SENs for the units for which he or she is responsible. When the units in a module have been coded, tested, and certified, they are ready to be placed under configuration management; at this point, the developer gives the SENs to the librarian who files them in the project library.
95
Section 6 - Detailed Design
MEASURES
Objective Measures
The objective measures used during the preliminary design phase are also the yardsticks used for detailed design, with one addition — CPU hours. The measures to be collected are as follows:
• The number of unit designs that have been certified versus the number identified
• Requirements questions and answers, TBDs, and changes
• Staff hours
• Estimates of system size, effort, schedule, and reuse
• Total CPU hours used to date
The source of these data and the frequency of data collection and evaluation are shown in Table 6-1. The paragraphs that follow provide specific recommendations for evaluating these measures during detailed design, and supplement the guidance given in Section 5.
Evaluation Criteria
The number of TBD requirements is a vital metric in this phase. Ideally, all TBD requirements are resolved by the end of the phase. If this goal is impossible to achieve, the management team must assess how the remaining TBDs will affect system size, system design, staff hours, costs, and schedule, and then evaluate the feasibility of continuing. In the flight dynamics environment, implementation should be postponed if "mission critical" requirements remain unresolved or if more than 10 percent of the total number of requirements are still TBD.
A large number of specification modifications in the detailed design phase is usually an indication that requirements and specifications are unstable or erroneous. The management team must assume that the level of specification modifications will remain high throughout the implementation and system test phases, and should reevaluate system size estimates and schedules accordingly (Figure 6-4).
By the end of preliminary design, managers know the projected number of units in the system. By the end of the detailed design phase, all units to be reused will have been identified, along with the degree of modification needed to incorporate them into the new system. Managers can combine these new figures with productivity rates from past projects to reestimate the effort hours and staffing
TBD requirements
requirements changes
size and effort estimates
96
Section 6 - Detailed Design
Table 6-1. Objective Measures Collected During the Detailed Design Phase
|
MEASURE |
SOURCE |
FREQUENCY (COLLECT/ANALYZE) |
DATA COLLECTION |
|
|
CONTINUED |
BEGUN |
|||
|
Staff hours (total and by activity) |
Developers and managers (via PRFs) |
Weekly/monthly |
* |
|
|
Computer use (CPU hours and runs) |
Automated tool |
Weekly/biweekly |
* |
|
|
Requirements (changes and additions to baseline) |
Managers (via DSFs) |
Biweekly/biweekly |
# |
|
|
Requirements (TBD specifications) |
Managers (via DSFs) |
Biweekly/biweekly |
* |
|
|
Requirements (questions/answers) |
Managers (via DSFs) |
Biweekly/biweekly |
* |
|
|
Estimates of total SLOC (new, modified, reused), total units, total effort , |
Managers (via PEFs) |
Monthly/monthly |
* |
|
|
and schedule |
||||
|
Status (units planned/ designed/certified) |
Managers (via DSFs) |
Biweekly/biweekly |
* |
r
o
"\
Recent SEL studies have shown that the relative cost of reusing existing units, as a percentage of the cost to develop the unit newly, is 20 percent for FORTRAN projects and 30 percent for Ada projects. The higher percentage for Ada is correlated to a significantly greater proportion of reused to new units on these projects as compared with FORTRAN efforts.
levels necessary to complete development. (See Table 3-2 of Reference 12 for guidance in computing these estimates.)
Near the end of the phase, size estimates can balloon unexpectedly if many units are moved from the "reused" to the "new" category. Managers need to ensure that decisions to create new units rather than reuse existing ones are justified and not merely a manifestation of the NIH ("not invented here") syndrome.
computer use
Computer use, as expressed in CPU hours or the number of sessions/job runs, is a key indicator of progress during design and implementation. On a typical flight dynamics project, a small amount of CPU time should be recorded during the design phases as the development team conducts prototyping efforts and enters PDL. Because Ada PDL is compiled, more CPU time should be logged on Ada projects.
97
Section 6 - Detailed Design
300000
260000
<2§ 220000 \. £ 180000
140000 **
100000
Symptom: Size estimates increase then drop during detailed design.
Cause: Excessive requirements changes and neffective change control mechanisms. Requirements that were deleted from specifications had to be restored during the implementation phase.
Corrective Actions: Assume that the instability of requirements will lead to a high level of specification modifications during implementation and testing. Analyze risks, replan size estimates accordingly, and request additional budget.
NOTE In the SEL environment, a large number of TBDs in the requirements and specifications, combined with a substantial number of requirements changes, typically cause a system to grow up to 40 percent larger than is estimated at the time of PDR. As the details of the unknown portions of the system become clear, the size estimate grows more rapidly. The range of accepted growth (shown in grey) narrows as the system becomes more defined.
Figure &4. Example of the Impact of Requirements Changes on Size Estimates — the UARS Attitude Ground Support System
A lack of CPU hours on a project that is three-quarters of the way through the detailed design phase should raise a red flag. The management team should investigate to determine whether the team is avoiding using the computer because of inadequate training or is mired in redesign as a result of specification modifications.
PRODUCTS
The development team's primary product for this phase is the completed design for the system, including unit prologs and PDL, as recorded in the detailed design document. In addition, the management team produces a build plan for implementing the design, and the development team begins to develop build test plans. These products are described in the paragraphs that follow.
98
Section 6 - Detailed Desk
r
(
NOTE
r
(
NOTE
as
itjb
Detailed Design Document
During the detailed design phase, the preliminary design report is expanded and refined to reflect the results of detailed design activities. Before CDR, this detailed design document is completed and distributed for review. The format and contents of the document are shown in Figure 6-5.
The Build Plan
-^ The build plan describes the strategy that will be
I k applied in constructing the system during the
implementation phase. The plan defines the sequence in which software components are coded and integrated into executable subsystems and the order in which these subsystems are combined into systems.
See SECTION 2 for definitions of the terms build and release and for guidance in determining the number of builds and releases that are needed as a function of project size.
1
Additional builds are required on projects using Cleanroom methodology. On Cleanroom projects, a build should consist of portions of the software that can be readily tested and integrated together and should last no more than 2 or 3 months.
The plan usually contains three parts:
An itemization of the capabilities that will be provided in each build or release
• The rationale, including relevant constraints, for providing specified capabilities in a particular build
• The implementation schedule
A preliminary build plan is usually generated during the preliminary design phase. During detailed design, the build strategy is expanded and refined until, at the conclusion of the phase, the updated strategy is included in the SDMP and presented for evaluation at the CDR.
Builds must be planned to accommodate user needs for operational capabilities or intermediate products. Plans must also allow for fluctuating and TBD requirements. Initially, the development team determines the optimum plan for implementing the system from a technical viewpoint. The management team then analyzes the plan and decides how it must be perturbed to accommodate the user, external (e.g., mission) schedules, specification modifications, and unknowns. Both the optimum and adjusted plans are presented at CDR.
99
Section 6 - Detailed Design
DETAILED DESIGN DOCUMENT
This document is the primary product of the detailed design phase. To complete the document, the development team updates similar material from the preliminary design report and adds greater detail. The suggested contents are as follows:
1. Introduction — purpose and background of the project, overall system concepts, and document overview
2. Design overview
a. Design drivers and their order of importance
b. Reuse strategy
c. Discussion and high-level diagrams of the selected system design, showing hardware interfaces, external data interfaces, interconnections among subsystems, and data flow
d. Traceability matrix of major components against requirements and functional specifications
e. Design status
(1) List of constraints, concerns, and problem areas and their effects on the design
(2) List of assumptions and possible effects on design if they are wrong
(3) List of TBD requirements and an assessment of their effect on system size, required effort, cost, and schedule
(4) ICD status
(5) Results of prototyping efforts
f. Development environment
3L Operations overview
a. Operations scenarios/scripts
b. System performance considerations
4. Design description for each subsystem or major functional breakdown:
a. Overall subsystem capability
b. Assumptions about and restrictions to processing in each mode
c. Discussion and high-level diagrams of subsystem, including interfaces, data flow, and communications for each processing mode
d. High-level description of input and output
e. Detailed description of processing keyed to operator-specified input and actions in terms of points of control, functions performed, and results obtained (both normal and abnormal, i.e., error processing and recovery)
f. Structure charts or object-oriented diagrams expanded to the unit level, showing interfaces, data flow, interactive control, interactive input and output, and hardcopy output
g. Internal storage requirements, i.e., description of arrays, their size, their data capacity in all processing modes, and implied limitations of processing
h. Detailed input and output specifications
(1) Processing control parameters, e.g., NAMELISTs
(2) Facsimiles of graphic displays for interactive graphic systems
(3) Facsimiles of hardcopy output
i. List of numbered error messages with description of system's and user's actions
j. Description of COMMON areas or other global data structures
k. Prologs and PDL for each unit (normally kept in a separate volume because of size)
5b Data interfaces — updated from description in preliminary design report (see Figure 5-5)
Figure 6-5. Detailed Design Document Contents
100
Section 6 - Detailed Design
Each build should address a coherent subset of the requirements and specifications and take three to five months to implement. Each build should cover a set of completed units; that is, the build plan should not require modifications or enhancements to individual units during later builds.
( TAILORING NOTE ^
( TAILORING NOTE (cont.)
In the flight dynamics environment, the initial build (B1) usually provides the core capabilities needed in a function- ing system. Middle builds (B2 to Bn-1) supply all critical capabilities. The last build (Bn) is restricted to "bells and whistles" and problem fixes.
r
(
NOTE
1
The build plans for flight dynamics projects also include the dates by which developers need to receive unit-level, analytic test plans from the acceptance test team. See SECTION 7 for detailed information about the purpose and content of these plans.
The first build must be kept simple, particularly if the development team is unfamiliar with the development environment or programming language being used. The next builds should address high-risk specifications and critical software capabilities, such as performance requirements, major control functions, and system and user interfaces. The build strategy must ensure that capabilities that can have a major impact on the software design are completed early, so that any problems can be handled while there is still time to recover.
Since the last build will grow to include the implementation of specification modifications and the resolution of problems remaining from earlier builds, it should be kept small in initial planning. The next-to-last build, therefore, must supply all crucial system capabilities. If specification modifications that add new features to the system are received during the implementation phase, additional builds that extend the phase may be needed to ensure that existing builds can proceed on schedule.
Build Test Plans
As soon as a build has been defined, the development team can begin to specify the tests that will be conducted to verify that the software works as designed and provides the capabilities allocated to the build or release. The development team executes the build test plan immediately following integration of the build.
The test plan for the first build is defined during the detailed design phase. Any modifications to the overall testing strategy that are made as a result of defining this first test plan are presented at the CDR.
101
Section 6 - Detailed Design
Test plans for the remaining builds are generated during the implementation phase.
The format and content of build test plans are described in Section 7.
CRTT1CAL DESIGN REVIEW
The detailed design phase culminates in the CDR. This review is attended by the development team and its managers, the requirements definition team and its managers, quality assurance representatives, user representatives, the CCB, and others involved with the system. Participants evaluate the detailed design of the system to determine whether the design is sufficiently correct and complete for implementation to begin. They also review the build plan to ensure that the implementation schedule and the capabilities allocated to the builds are feasible.
The emphasis at CDR is on modifications
— to requirements, high-level designs, system operations, and development plans
— made since the PDR. Speakers should highlight these changes both on the slides and during their presentations, so that they become the focus of the review. The CDR also provides an opportunity for the development team to air issues that are of concern to management, the mission project office, quality assurance personnel, and the CCB.
f TAILORING NOTE ^
■
For very large projects , a CDR should be held for each major subsystem and/or release in order to cover all aspects of the system and to accommodate changing requirements. On such projects, it is vital to have one review, i.e., a System Design Review, that covers the entire system at a high level.
r
o
W
Figure 6-6 shows the recommended CDR format. An outline and suggested contents of the CDR hardcopy material are presented in Figure 6-7. Note that material that was covered at PDR is not presented again, except as needed to contrast changes. For this concise format to be effective, participants must be familiar with the project
background, requirements, and design.
They should have attended the PDR and studied the detailed design document before the meeting.
Reviewers should address the following questions:
• Does the design satisfy all requirements and specification ?
REUSE NOTE
\
At the CDR, developers present statistics snowing the number ' and percentage of components to be reused, and which of these are drawn from the RSL. They also present key points of the detailed reuse strategy, identify any changes to the reuse proposal that have been made since PDR, and describe new/revised reuse tradeoff analyses.
102
Section 6 - Detailed Design
CDR FORMAT
Presenters — software development team
Participants
• Requirements definition team
• Quality assurance representatives from both teams
• Customer interfaces for both teams
• User representatives
• Representatives of interfacing systems
• System capacity/performance analysts ■CCB
Attendees should be familiar with the project background, require- ments, and design.
Schedule — after the detailed design is completed and before implementation is begun
Agenda — selective presentation of the detailed design of the system. Emphasis should be given to changes to the high-level design, system operations, development plan, etc. since PDR.
Materials Distribution
• The detailed design report is distributed at least 10 days before the CDR.
• Hardcopy material is distributed a minimum of 3 days before the review.
Figure 6-6. CDR Format
Are the operational scenarios acceptable?
Is the design correct? Will the transformations specified produce the correct output from the input?
Is the design robust? Is user input examined for potential errors before processing continues?
Have all design guidelines and standards been followed? How well have data usage and access been localized? Has coupling between units (i.e., interunit dependency) been minimized? Is each unit internally cohesive (i.e., does it serve a single purpose)?
Is the design testable?
Is the build schedule structured to provide early testing of end- to-end system capabilities? Is the schedule reasonable and feasible for implementing the design?
103
Section 6 - Detailed Design
1.
2.
4.
& 7. &
10.
11. 1Z
13. 14. 15.
HARDCOPY MATERIAL FOR THE CDR
Agenda — outline of review material
Introduction — background of the project, purpose of the system, and an agenda outlining review materials to be presented
Design overview — major design changes since PDR (with justifications)
a. Design diagrams, showing products generated, interconnections among subsystems, external interfaces
b. Mapping of external interfaces to ICDs and ICD status
Results of prototyping efforts
Changes to system operation since PDR
a. Updated operations scenarios/scripts
b. System performance considerations
Changes to major software components since PDR (with justifications) Requirements traceability matrix mapping requirements to major components
Software reuse strategy
a. Changes to the reuse proposal since PDR
b. New/revised reuse tradeoff analyses
c. Key points of the detailed reuse strategy, including software components to be reused in future projects
d. Summary of RSL contributions — what is used, what is not, reasons, statistics
Changes to testing strategy
a. How test data are to be obtained
b. Drivers/simulators to be built
c. Special considerations for Ada testing
Required resources — hardware required, internal storage requirements, disk space, impact on current computer usage, impacts of compiler
Changes to the SDMP since PDR
Implementation dependencies {Ada projects) — the order in which components should be implemented to optimize unit/package testing
Updated software size estimates
Milestones and schedules including a well-thought-out build plan
Issues, risks, problems, TBD items
a. Review of TBDs from PDR
b. Dates by which TBDs and other issues must be resolved
Figure 6-7. CDR Hardcopy Material
104
Section 6 - Detailed Design
EXTT CRITERIA
To determine whether the development team is ready to proceed with implementation, the management team should consider the following questions:
• Are all design diagrams complete to the unit level? Have all interfaces — external and internal — been completely specified?
• Do PDL and prologs exist for all units? Have all unit designs been inspected and certified?
• Have all TBD requirements been resolved? If not, how will the remaining TBDs impact the current system design? Are there critical requirements that must be determined before implementation can proceed?
• Have the key exit criteria for the phase been met? That is, has the detailed design document been completed, has the CDR been successfully concluded, and have responses been provided to all CDR RIDs?
When all design products have been generated and no critical requirements remain as TBDs, the implementation phase can begin.
105
Section 6 - Detailed Design
106
Section 7 - Implementation
LIFE
CYCt£
PHASES
REQUIREMENTS OEFIMTION
REQUIRE- MENTS ANALYSIS
PREUMI
NARY
DESIGN
OETAlLED DESIGN
IMPLEMENTATION
SYSTEM TESTl\a
tanceI riNQ I
ACCEPTANCE TESTING
SECTION 7 THE IMPLEMENTATION PHASE
—^^^^™^— ■■"""■" IMIMh*J' ' "■■■■■■■■■M....MMit*^..frM.tt...i.M...^«.,^^ .. •■ ■■■■■|| Y ■ mi |
ENTRY CRITERIA
• Detailed design document generated
• CDR completed
• CDR RIDs answered
PRODUCTS
• System code and supporting data
• Build test plans and results
• System and analytical test plans
■ — '■■'■■■■■ ,-:/...».-ga-.vw.g , ...'....-.. .S"
s
EXIT CRITERIA
•All system code and supporting data generated and tested
• Build test plans successfully executed
• System test plan completed
• User's guide drafted
wwwti.
MEASURES
Units coded/ code-certified/ test-certified vs. units identified
• Requirements Q&As, TBDs, and changes
• Estimates of system size, effort, schedule, and reuse