Making systems

Table of contents

• Part VII: Specifications
• Chapter 31: System purpose
• 31.1 Introduction
• 31.2 Why do this?
• 31.3 Different kinds of projects
• 31.4 Investigating purpose
• 31.5 Recording purpose
• 31.6 Validating purpose
• 31.7 Change of purpose
• 31.8 Using purpose
• Chapter 32: System concept
• 32.1 Copied in
• 32.2 Purpose of concept development
• 32.3 Concept development work
• 32.4 When the concept is complete
• 32.5 Evolving the concept
• 32.6 Concept development for different kinds of projects
• 32.7 Artifacts
• Chapter 33: Specifications
• 33.1 Purpose
• 33.2 Specifications and systems
• 33.3 Example
• 33.4 Kinds of specifications
• 33.5 Using specifications in a system
• 33.6 Using specifications for a component
• 33.7 Specification artifacts
• Chapter 34: Requirements
• 34.1 What are requirements?
• 34.2 A single requirement
• 34.3 Multiple requirements
• 34.4 Organizing requirements
• 34.5 Writing good requirements
• 34.6 Requirement derivation
• 34.7 Advanced requirements
• 34.8 Analyzing requirements
• 34.9 Validating requirements
• 34.10 Verification
• 34.11 Limitations of requirements
• 34.12 Working with requirements
• 34.13 Tools
• Chapter 35: Models
• Chapter 36: Interface definitions
• Part VIII: Design
• Chapter 37: Design introduction
• 37.1 Purpose
• 37.2 How designs are used
• 37.3 Design artifacts
• 37.4 Developing designs
• Chapter 38: Breakdown structure
• 38.1 What is the component breakdown for?
• 38.2 Basic concepts
• 38.3 Component identifiers
• 38.4 Viewing the breakdown structure
• 38.5 Context and relationships
• 38.6 Advice
• 38.7 Examples
• Chapter 39: Component design
• 39.1 Form
• 39.2 State
• 39.3 Actions or behaviors
• 39.4 Interfaces
• 39.5 Non-functional properties
• 39.6 Environment
• Chapter 40: Good design practices
• Chapter 41: Prototyping
• Chapter 42: Budgets
• Chapter 43: Safety and security design
• Chapter 44: Design for shared resources
• Part IX: Implementation
• Chapter 45: Introduction
• Chapter 46: Good implementation practices
• Chapter 47: Integration-first implementation
• Chapter 48: Skeletons and mockups
• Chapter 49: Implementation using testing
• Part X: Verification
• Chapter 50: Introduction
• Chapter 51: Recording evidence
• Chapter 52: Good verification practices
• Bibliography

Part VII: Specifications

The first part of the life cycle: purpose, concept, and specification.

Chapter 31: System purpose

31.1 Introduction

A system’s purpose is the set of things that it should achieve for different stakeholders (Chapter 9). The purpose is a record of the reasons for investing resources and time into making the system. The purpose gives direction for all the work developing a concept and design for the system. A system is acceptable if it meets its purpose; anything in the system that does not contribute to the purpose is waste.

The development of every system and every component should begin with establishing its purpose. Understanding purpose is the first step to working how the specifications for a system or component. Trying to develop a concept or specification without working out purpose means developing the wrong thing. In Section 9.2, I laid out why it is important to work out purpose first.

The purpose for an entire system is likely to be complex, and it will take time and effort to find out the purpose. The understanding of the purpose for a system—or a complex component of it—is likely to evolve as time goes by, because people won’t realize everything they want all at once. The full understanding usually comes iteratively, as stakeholders review system concepts and discover something they missed.

Some components have simple purposes. The purpose for a bolt, for example, is just to connect some physical components. Knowing what those components are, what they are made of, the environment the assembly will be in, and what forces the bolt must handle are most of the purpose. This kind of purpose does not need a drawn-out investigation or a complex record. It does still need to be established and written down, however.

The input to developing purpose is usually vague and unorganized. It includes general ideas for a system and who might be interested. It proceeds through discussions with potential customers and background research on them. It can include market research when a system might be built to sell to as yet unidentified customers. It can also include documents from a potential customer, such as a request for proposals (RFP).

The output of purpose development is a set of documents or other records. The primary output is a statement of who the system stakeholders are, and what they need or want. The output also should include the unedited, uninterpreted records of what customers or stakeholders said, so that the final record of purpose can be checked against the original information. Maintaining a record of how the team has learned to interpret what a customer said also helps check the final result.

The general approach to developing the purpose is as follows:

• Work out who will be using the system or component—who the stakeholders are.
• Investigate their needs, recording their direct input for future reference.
• Document those needs in an organized way.
• Have the stakeholders review the relevant parts of the documented needs to ensure it accurately captures what they mean.
• Iterate until all the stakeholders are satisfied and the documented purpose is clear enough to proceed to developing a concept for a solution.

Parts of this process will repeat as concept, specification, and design proceed. When parts of the purpose change, people need a clear indication of the difference between the old and new purpose so that they can determine what needs to be changed in concept, specification, or design to meet those changes.

31.2 Why do this?

I have been told on more than one project: “We can’t afford to do this up-front stuff. We need to move fast and get something working.”

My response has been along the lines of: “Moving fast to get where?”

There are three reasons to take the time at the beginning of a project to work out the system purpose.

1. How often do people actually know what a customer needs before doing homework?
2. The beginning of the project is the time to build relationships with stakeholders.
3. Get the purpose wrong, and it sticks. If a system gets developed that customers don’t like, they won’t forget it—even if it is improved later.

There are occasional exceptions to each of these, but they are not common for complex systems.

The Pontiac Aztek SUV offers an example. It was an automobile marketed by General Motors from 2001-2005 (model years). It was designed to appeal to customers in a new market segment for smaller SUVs, and the company put effort into making it new and exciting. It was a failure for GM: it sold poorly and never met break-even sales. It was often described as one of the ugliest cars ever produced.

The company went ahead and produced the vehicle. It has been reported that the team worked hard to develop the model faster than had been typical of the company at that point. By some accounts, the project’s execution went smoothly and met its milestones. Nonetheless, all the effort was in vain.

The Aztek project shows all three reasons for spending time working out purpose. The project believed they knew what people wanted better than the customers they surveyed did, and they were wrong. The company failed to build relationships with potential customers who were telling them that the car was not attractive. And once the car was available, the public stigma was so great that even the changes they made in subsequent years and marketing efforts did not help sales.

This example is far from unique. I discussed other projects that did not fully work out the system purpose in Sections 4.1, 4.3, and 4.4.

There is one case where the principle of establishing a customer’s purpose for a system does not apply: when building a new kind of system for which there is not yet a customer. For example, a technical demonstration system is used to learn about the technical problems of a potential system design approach before committing to making a product using that approach. The Boeing 367-80 (the “Dash 80”) in the early 1950s is a good example [Thompson87]. It tested a design that evolved (separately) into the 707 passenger aircraft and the KC-135 military tanker aircraft—but neither of those aircraft were exactly the Dash 80. The Dash 80 tested new wing and engine pod designs, thrust reversers, landing gear, and more. The Dash 80 also gave flight demonstrations to airlines that showed that the aircraft was up to the task of carrying passengers economically.

Technology demonstration project still have stakeholders, even if they do not result in a system that will be used directly by customers. Funders are still providing resources to build the system, and they expect a return on that investment, such as learning enough that the organization can build a “real” version as a product. Regulators may have a stake in how the system operates. The project may have to make a case to the funder or others in order to get the investment for the work. In Chapter 25, I discussed making the case for a project.

31.3 Different kinds of projects

The purpose is all about knowing what the customer and other stakeholders want. But who is the customer? How does one learn what they want? There are multiple answers to these questions, and how one learns about purpose depends on those answers.

I divide projects into three general groups:

• Customer-driven, where there is a specific customer who wants the system. One can learn what this customer wants by talking to them. This is typical of internal customers, or customers who have an ongoing contractual relationship with the development organization.
• RFP-driven, where there is a specific customer. This customer is following an acquisition process where they provide a request for proposals (RFP), and the team must respond with a proposal for developing the system. The customer is often constrained in how they can communicate about their needs in order to be fair to all proposers. This is typical of government contracting.
• Visionary, when there is not a specific customer yet, and possibly not even a defined market for the system. This is typical of commercial products that will be marketed to many customers once it is created. Developing the purpose includes working out the market segment or set of potential customers for the system.

31.4 Investigating purpose

The process of coming to understand the purpose for a system has a few steps. These do not proceed neatly linearly; they overlap and repeat. The purpose of the process is to identify who all the stakeholders involved in the system, and come to an accurate and complete understanding of what each of them needs. The process of understanding each stakeholder itself has multiple steps. After one works out what each stakeholder needs for themselves, the last step is to synthesize a common purpose out of all of the stakeholders’ needs.

The task of understanding a stakeholder’s needs will only generate useful results if the results are accurate. This means that the team is careful to separate what the stakeholder actually says from what the team thinks they will be saying. It means that the team does not fill in gaps in what the stakeholder says—they may ask the stakeholder to fill it in, but the team does not supply the information. Most of all, the team works to avoid confirmation bias; they treat their understanding as it evolves as a hypothesis and devises ways to check whether the hypothesis is correct or not.

31.5 Recording purpose

• recording purpose
  • source documents (transcripts, notes) that are unfiltered
  • extracted and summarized user statements
  • organized objectives and constraints
• keeping purpose focused
  • how to decide whether to include some objective or not
  • market segmentation as part of the basis

31.6 Validating purpose

• mapping user statements to objectives and constraints, and showing them the objectives/constraints
• use a mockup, prototype, or paper version
• feed back concept when that is developed from the objectives and constraints

31.7 Change of purpose

• detecting when users/stakeholders start talking about something new
• hooking into the change request process for explicit changes
• deciding whether to change part of the purpose
• estimating effects of a change

31.8 Using purpose

• guiding concept and specification
• validating designs and implementations
• basis for contracting and proposals
• basis for evaluating change requests

Chapter 32: System concept

32.1 Copied in

work to build a concept

• come up with lots of possible approaches
  • sketch out parts of system structure or concept of operations
• evaluate them as to whether they will help meet the need or not, and whether they are technically feasible (trade studies), sometimes combining best aspects of different approaches
• evaluation includes seeing if there is some available component, or some technology available, or some prior experience on which some top-level component can be based
• evaluation also includes back-of-the-envelope analyses of how difficult something will be to design and implement (time and resources, not uncertainty/risk), and how well it supports stakeholder needs (likely to meet performance or scale? fit with security and safety?)
• mapping out the flow to achieve some external behavior reveals gaps in internal structure
• along the way, track which stakeholder needs are being met and work out how to fill gaps
• often find that some part of the stakeholder needs worked out in the previous phase are insufficient or incomplete or inconsistent, causing some part of the purpose development to rewind to fill in the gap in purpose

XXX rewrite to reduce use of conops term

XXX harmonize stakeholders with list from earlier chapters

XXX harmonize concept contents with earlier chapters

XXX pull out document management section

XXX split purpose and purpose investigation out from concept

XXX discuss internal and external view, consistent with section 26.4 on concept development phase

32.2 Purpose of concept development

At the very beginning of a system development project, there is generally only a rough idea of what the system should be. The understanding of the system objectives is too vague to launch into development or writing tests right at the start.

The purpose of developing the initial system concept is to get a reasonably clear initial definition of what the system should be or do. The definition should accurately reflect what the customer needs (whether the customer is an actual customer or a representative of an expected customer). The definition need not be perfect; it will be revised as the project moves forward and the initial concept gets validated or the understanding of the customer’s needs improves.

Internal to the project, the initial concept provides the information that the team needs to begin working out the structure or architecture of the system and to begin writing the high-level system specification. In the absence of a well-structured concept, the development team cannot begin working out how to implement the system without taking risks that the design is wrong and will have to be redone.

Outside the project, concept development supports the relationship between the project and the customer. Clear agreement between the customer and the development team makes for efficient and less fraught development. Agreement on the concept can support writing a contract for development that protects both the development team and the customer from feature creep or extra costs.

The documentation of the concept will be used throughout the entire life of system development and operation. The concept is the record of the big picture for the system. While it gathers the information needed to guide system design, the big picture is also important to new people joining the team who need to learn about the system they will be working on. The concept also serves management as a definition of the goal that system development is trying to reach, allowing the team to check from time to time whether they are designing and building the right thing. In that way a good definition of the concept is essential to being able to validate the system design.

32.3 Concept development work

The concept development work in a project seeks to establish a clear statement of what the system should be and do. At the end of the work, there should be a record of the customer’s objectives for the system, a concept of operations that embodies those objectives and explains what the system is, and review and approval from both the customer and the project leadership.

The core of this is to determine and record what the customer wants. This is rarely an easy task: there may or may not be a well-defined customer, and the customer may or may not be able to articulate what they need and what they want.

Start with working out who the customer is. Some projects are customer driven, meaning that there is a customer for the system and the project is working in response to that customer’s needs. A customer who contracts with a development team to build a system for them is the simplest example of this kind of project. Other projects are RFP driven, meaning that there is a customer but they are asking one or more teams to propose a system design before committing to funding development. These projects differ from customer driven projects in that the customer provides a request for proposal (RFP) that should contain all the information needed about what the customer wants. (In practice the RFP is rarely sufficient.) Still other projects are visionary, meaning that there is no specific customer driving what the system should do, but instead the system is being designed in the expectation that there will be customers for the system in the future. This kind of project includes innovative systems that are expected to help create a market for themselves.

Every project should document who their customer is and how they work. Where there is an actual customer, this should include information about how they make decisions about systems, who the decision-makers and influencers are, and any contacts that might be able to provide background information or advice about the customer. For visionary projects, common practice is to develop a profile of one or more hypothetical customers, including how they are expected to decide whether to acquire a system and where information can be found to characterize these potential customers.

A document recording what the customer wants is the first major work product in the concept development phase. This document serves as the primary record of what the customer has asked for. It is used in later work to check whether the interpretation that the development team puts on what they think they have heard from the customer is accurate. It is vital that the customer objectives document be free of biases that the project team brings, because this document is used to detect when the team have applied their biases.

The customer objectives document, therefore, should be written using the customer’s own language, and should only be a summary of what the customer has said. One way to achieve this is to collect primary source material from the customer—such as notes or recordings from meetings, a request for proposals, or externally-sourced market analyses—and then write a summary of their contents. If possible, the summary document should include references to the primary sources so that someone can check the summary for accuracy. Writing the objectives document as prose, or as a bulleted list, is reasonable. The customer objectives document should not be organized into formal requirements; that step comes later and formal requirements should derive from the customer objectives document.

Where possible, the customer objectives document should be shared with the customer (or representative potential customers) to validate that the document is accurate. It is normal for there to be many iterations with the customer to get the details right; indeed, that is the point of gathering the customer objectives.

The next major document, or collection of documents, records other constraints on the system’s design. This includes things like

• Regulation to which the system or the development team must adhere
• Company or organization standards and objectives, including business objectives, safety objectives, and security objectives
• Customer standards that apply to the project

This document of other constraints should reference the source material for each kind of constraint.

With the customer definition, customer objectives, and constraints documented, the team can develop a concept of operations, or CONOPS. This document records a simple model of how the system can be structured and operate at a high level. The contents of the CONOPS should be limited to how the system will interact with things outside itself, whether that is the function and structure that the customer will see, the interactions with other systems, or its interactions with regulatory organizations. The CONOPS should be fairly brief, and diagrams are helpful. The CONOPS should not become a specification of the system’s design; again, the specification and design are derived from the CONOPS. The CONOPS document is often written in the language that the development team uses. It is common to use graphical notation standards for some elements where appropriate.

The contents of the CONOPS should derive from the customer objectives and other constraints. A good CONOPS document will include references to those sources to show why the concept is structured the way it is.

At the end of the concept development phase, the team will have gathered information about what the system needs to be, both to satisfy the customer and to satisfy other stakeholders, and created a conceptual version of the system’s functions in the CONOPS.

The CONOPS should be shared with the customer for their review and approval. Because the CONOPS document is written for the development team using the team’s language, it is often necessary to interpret the contents of the CONOPS to the customer. The customer should validate that the functions included in the CONOPS cover everything they are expecting. The development team’s management should also review and approve the concept material to validate that it meets organization policies and regulatory needs.

Sidebar: Stages of working out the system concept

Some people have asked: what is the difference between the customer objectives, concept of operations, requirements, and design? Why have all these different documents? Why not begin by recording requirements?

We view the process of working out the system’s concept as a multistage flow, starting with a vague idea and ending in a concrete specification, including requirements, for what the system should do. The flow is:

The customer objectives and concept of operations documents deal only with the concept of the system—the abstract general functions and purpose. Most importantly, they should be understandable by the customers, who look at them to see if their ideas and needs are being reflected in the system that will be designed.

Take requirements, for example. The content of every top-level requirement that goes into the system specification should be present in the customer objectives and concept of operations, but the information should be recorded informally, accompanied with explanation of the context and purpose of each function. These will be translated into requirements in the system specification, which have a strict format and are typically recorded in a database that is not easy for customers who are not also trained in systems engineering to follow.

32.4 When the concept is complete

The goal for the initial concept development phase is to have a clear but informal understanding of what the customer wants, what constraints other stakeholders place on the system, and agreement from all the parties that the documented understanding is correct, so that the team can move on to formalizing the design of the system.

Put another way, the system design efforts depend on knowing what the system is supposed to do. The amount of effort put into system design should be low until the team has confidence that they understand what the system design should do.

Specifically:

• The team has confidence that it has a clear and complete idea of who the customer is and what the customer’s objectives are
• The team has confidence that it has an accurate understanding of other constraints that will be placed on the system
• The team has developed a concept of operations that plausibly addresses the customer objectives
• The customer (or their proxy) can confirm that the team has understood their needs
• The team’s management can confirm that the system described in the concept of operations is likely both to be feasible and to meet the organization’s business objectives

32.5 Evolving the concept

The concept for the system will change over time. This can happen in the early stages of a project, when one is still working with the customer for the first time to understand their objectives. It also happens later: when the customer’s needs change, when the team realizes that they have misinterpreted the customer’s objectives, or when regulation changes.

In general terms, while working to develop the system concept for the first time, any changes can be made as needed. At some point, the initial versions of the concept documents will be “done”, reviewed, and approved. The documents are then baselined: marked as stable, meaning that people can use the information in the baselined concept documents to develop system architecture and specifications without worrying that the documents will be shifting on them all the time.

After the concept has been baselined, the team must follow a more careful process to make changes. First one identifies what has changed: a change in the customer objectives, or in constraints such as regulations. Next one analyzes the change to determine where the concept documents need to be revised. The revised document versions exist in parallel with the baseline version, but only the baseline version is official until the revised documents are reviewed, approved, and marked as the new baseline.

When the baseline version is updated, changes may need to propagate to other documents. For example, the system architecture and specifications derive from the concept documents. A change that adds a function to the system concept in the CONOPS document will induce changes to the architecture (possibly adding new components) and specifications (adding functional requirements to some components‘ specifications). If the change happens late in the project, when parts of the system have been implemented and verified, the change may propagate all the way to updated software, hardware designs, and test cases.

This explanation of the process simplifies the steps somewhat: individual documents are versioned or baselined. A change to the customer objectives results in an updated version of the objectives document. This leads to an updated version of the CONOPS, which in turn can lead to a need to review and approve the updated CONOPS, as shown in the diagram above. The new versions of the documents should not be baselined until they have collectively been reviewed and approved. They should be baselined together, so that the official, stable versions of all the documents remain consistent with each other. This means that updated versions should remain work in progress until the review step has been completed.

32.6 Concept development for different kinds of projects

XXX part of this moved to previous chapter; slim down

Concept development is all about knowing what the customer wants. But who is the customer? How does one learn what they want? There are multiple answers to these questions.

We can divide projects into three general groups:

• Customer-driven, where there is a specific customer who wants the system. One can learn what this customer wants by talking to them. This is typical of internal customers, or customers who have an ongoing contractual relationship with the development organization.
• RFP-driven, where there is a specific customer. This customer is following an acquisition process where they provide a request for proposals (RFP), and the team must respond with a proposal for developing the system. The customer is often constrained in how they can communicate about their needs in order to be fair to all proposers. This is typical of government contracting.
• Visionary, when there is not a specific customer yet, and possibly not even a defined market for the system. This is typical of commercial products that will be marketed to many customers once it is created.

32.6.1 For customer-driven projects

Customer-driven projects are those that have a specific customer whose needs or desires drive what the system should do. The development team is focused on satisfying this specific organization.

In these projects, the development team can communicate with the customer to learn how the customer works and what their needs are. Ideally, the customer will be involved all through system development, so that the team can check what they are building directly with the customer.

The Agile Development approach to software development grew out of customer-driven projects. The Agile approach advocates for the customer being continuously involved, including helping to prioritize work in each development sprint. This kind of direct involvement is only possible when the development team can interact constantly with the customer. Note that we do not advocate dogmatic Agile Development (nor do we think many projects actually use it); we will discuss this more in chapters on validation and management.

Some customers will begin working with the team with only a general concept in mind. The team will need to draw out from the customer what that concept means, and explore all the corner cases with them.

Other customers will bring a partially-developed concept of what they want. In these cases, the team must, first, ensure that they properly understand what the customer is saying, and second, explore the concept with the customer to find any missing information.

Working with a customer on the concept is full of pitfalls. The most serious is that the team will interpret what the customer is saying in a way that the customer does not actually mean. The development team can bring their own interpretations to understanding what the customer says; the result can be a system design that doesn’t meet the customer’s actual needs. The team should use communication techniques that allow them to validate their understanding of what the customer is trying to say, such as active listening ! Unknown link ref methods. The key ideas in these techniques are

• To read back in paraphrase to the customer what the team has heard
• To ask clarifying questions when someone thinks there may be multiple interpretations of a statement, and
• To ask open-ended questions rather than prompting the customer for a particular answer.

There are many references available on these techniques.

The concept needs to include everything that the customer actually wants. Most commonly, the customer will be thinking about the most important functions they need but will not be considering all of the other functions that are needed to make the important functions work.

The team needs to work with the customer to elicit these other functions or use cases. While there is no recipe for finding all these other use cases, we have found that there are some questions that help ferret them out.

• For use cases that the customer is thinking about, how does the system get set up to be ready to start that use case? For example, for an aircraft autopilot, what conditions must be true for it to operate? How does a pilot set it up and engage it?
• For each step of the use cases, what happens if something goes wrong? Or if a user changes their mind? For a banking system, what happens if a user is part way through setting up a transaction and realizes they entered the wrong amount in an earlier step? What happens when an aircraft’s engine stops working during a takeoff roll?
• How does the system go through its life cycle? If multiple instances will be manufactured, how are parts supplied? How is it manufactured and tested? How is it disposed of?
• What maintenance will be required? Are there mechanical parts that require regular inspection and replacement? Are there information components with logs that will fill up?
• If the system has users who are authenticated, how are user accounts managed? What are the assumptions about the users? How are they vetted or trained? For example, what training or licensing does a pilot require for a new aircraft design?
• Who are the regulators or other responsible organizations, such as courts or industry trade groups, who may be called upon to audit the system’s operation?

32.6.2 For RFP-driven projects

An RFP-driven project is one where a customer is asking for proposals from development teams about how they will design and build a system. The customer is usually asking for multiple, competing teams; the customer will choose one or more teams for a contract to build the system.

The customer writes a request for proposals (RFP) document that defines both the characteristics of the desired system and how the customer expects to judge between multiple competing proposals, if there are any. The RFP should thus document the customer’s objectives. In many competitive acquisition cases, the RFP must be the only official source that a team can have so that all proposing teams work from the same information—thus treating all teams equally.

When deciding to respond to an RFP, the team must learn what acquisition rules the (potential) customer is using in order to determine what restrictions to follow when communicating with the client. The team must also learn how the customer makes decisions, including who makes the decisions, who influences the decisions, and how the decision will be made. When responding to a commercial RFP, this can be easy: there is a contact who sends out the RFP and who can answer questions as needed, there is someone they work for who reviews and decides whether to accept a proposal or not, and the decision is based on what the decision-maker thinks meets their needs at the best price. For a US Government agency RFP, on the other hand, the decision process is defined by Federal Acquisition Regulations and by the agency’s supplemental rules. There are formal processes for submitting questions; there is typically a defined scoring and weighting system that a formal review team must use to rate each proposal.

The information gathered about how the customer communicates and makes decisions should be included in the Customer Definition document.

When the customer is doing a competitive acquisition, the team also needs to gather information on the other teams that may be choosing to submit a proposal. This information helps shape the proposed design and the proposal itself to make them look better than the competition to the customer. This can include relative strengths and weaknesses of the other teams, such as whether this team has proprietary technology that will do a better job for the customer (a weakness of the other team), or whether the other team has more flexibility in pricing (which might be a strength of the other team). This information should be gathered into a Competition document.

In practice RFPs are rarely complete or unambiguous. This is because they are written only by the customer, and there is little opportunity for dialog so that the customer can get alternative perspectives and check that their work is clear and complete. When it is possible, the team should engage in the kind of dialog with the customer that they would in a customer-driven project in order to confirm their understanding of what the RFP says and to flesh out the request to include a more complete picture of what the customer actually needs. When this is not possible, the team should find people who can accurately represent the customer’s way of thinking and needs, such as people who have a similar position in a different organization in the same industry, or someone who has worked closely with the customer in the past and knows the business or people involved.

Whether one can get clarifying information or not, the concept documents should include documentation on where the team has made assumptions or interpretations of the RFP source material. These points are matters where there is greater than usual risk that the team’s assumption does not match what the customer is thinking. This means that there is a higher than usual risk that the concept or design that the team proposes will be interpreted differently than what the team means—and so it is worth putting extra effort into making those parts of the proposed concept or design as clear as possible.

There are two end results of the process for responding to an RFP: first, a decision whether to complete and submit a proposal, and second, submitting a proposal if the first decision is positive.

The decision about whether to submit a proposal or not depends on

• Whether the team has the resources to pursue the work
• Whether the team has a reasonable chance of winning a contract, and
• Whether building the system would be worthwhile.

Determining whether the team has resources requires estimating the resources needed. For the first steps of concept development, this may be small, perhaps one or a handful of people to gather information and to get an initial understanding of what the customer wants. As the work progresses, more resources will be needed—to gather more information, to do concept development, to gather competitive market data. At each step of the process, it will become clearer how many people or other resources are needed for the next step of developing the proposal. At the same time, the team must be able to estimate how much resource will be needed to build the system if they win a contract. This will be unknown to start, but as the system concept and architecture work move forward the estimates will improve. The team must develop the architecture enough to be able to determine prices to charge the customer and to be able to determine if the team will have the capacity to do the work. These analyses grow out of the concept of operations and later architecture documents.

Determining whether the team has a reasonable chance of winning is a combination of knowing how the customer will judge proposals, how strong other teams are likely to be, and how well this team can satisfy the customer. This information is gathered in the Customer Definition document, the Competition document, and in how the Concept of Operations and architecture respond to the customer’s objectives.

Finally, determining whether building the system can be worthwhile depends on knowing what the team’s organization values. Does the organization require a particular profit margin? Is there a minimum or maximum contract price that is considered “interesting”? Does the system fit within the organization’s business strategy? These kinds of questions are captured in the Business objectives document, and analyses use customer objectives, CONOPS, and architecture documents to develop an answer to them.

Developing proposals is a complex specialty, and much has been written about it. We refer the reader to ! Unknown link ref for further reading.

32.6.3 For visionary projects

A visionary project, as we are using the term, is one where the system being designed and built is not for a specific, existing customer. Instead, the system might be marketed to several potential customers down the line, or the system might be part of a strategy to change an existing market or create a new one, thus creating new customers who may not even exist yet.

Consider building a new commercial passenger transport aircraft. The air transportation system is mature, and so one can name who buys these aircraft: airlines, aircraft leasing companies that provide the aircraft to airlines, businesses using aircraft for private transportation, and government organizations that fly passenger aircraft. No aircraft company in recent decades has built a new large passenger aircraft to be sold only to a single customer; instead, the companies work out the needs of many potential customers and design an aircraft that will be good for many of those customers. Since airlines come and go often relative to the lifetime of an aircraft design, many of the potential airline customers do not yet exist when the aircraft company has to decide on the capabilities of the new aircraft. This is a case where the market exists but there is not a single customer to satisfy.

In contrast, consider the first generation of global satellite data and telephony networks (such as Iridium and Globalstar). When they were being designed, there was no mass market of ground-to-space mobile communications. These companies, and others that did not end up deploying their networks, had to work out who their potential customers might be and what they might need. Indeed, all of these first generation providers went bankrupt at some point as they developed both their network systems and at the same time built up a subscriber base. This is an example of a project that was creating a new market.

In both these cases, there is not a single definition of a customer. Instead, the team must determine the market—the set of customers—who might want the system. The team looks for the set of features or capabilities that will satisfy a large enough market to be worth supporting. The plan will often be to start with a small market segment and grow over time by adding capabilities to satisfy more people, while having learned more about the first set of customers and gaining some revenue to help fund growth.

All this information will need to be collected from a number of sources, including market analysts, surveys of potential customers, and the experience of people who have worked in related industries. Finding people or organizations who can act as a proxy for a class of possible customers is helpful. It is important to gather from multiple sources in order to cross-check the information and to account for sampling bias that can happen if information comes from only one perspective.

The information about the target market segment(s) will change regularly over the course of the project as customers come and go, or as new opportunities appear. This means that the design and implementation of the system will likely need to adjust as time goes by. This also means that the team needs to continue to survey the market and talk to potential customers.

At the same time, it is a rare project that can successfully chase arbitrarily changing customer objectives. The design and implementation team needs enough stability that they can complete a version of the system. Marketing and sales teams need stability so that they know what they can actually sell to a customer. The stable version of the customer objectives should be baselined (see section on configuration management below). Changes to the baseline should occur only periodically, when the team decides that either there is a change in the understanding about customers that is vital to reflect in the design of the system right away, even at the cost of delaying the system being ready for use, or when there is a change that does not delay or significantly change the system being designed and built right now.

The idea of a minimum viable product (MVP) is fashionable in recent years. The general approach is to create the simplest system that will meet the needs of just a few customers, put the team’s focus on building up that first version, then plan on adding capabilities as time goes by to make the product attractive to more customers. This is an example of planning how to handle changes in understanding what customers want.

Visionary projects can expect that there will be competition with other teams’ products. Indeed, customer choice is a fundamental precept of the Western market system, and often required by regulation. A team should develop a record of what their competition might be, whether that is another organization offering a similar product (as happens with large passenger aircraft), or whether a customer could meet their needs a different way, or whether customers will choose no to buy a new product and live without its benefits (which is common with new technology trying to create a new market). The team should also build up an analysis of what sets this team’s system apart from alternatives—why a customer would choose this system over other options. Maintaining the Competition document with this information will help the team make decisions about changes to the customer objectives or business objectives around which the team is designing the system.

32.7 Artifacts

The concept development phase involves artifacts such as the customer objectives and concept of operations. We can now define each of these artifacts, but first we will address document management as a necessary supporting capability.

32.7.1 Document/configuration management

Each of the artifacts worked on and produced in the concept development effort should be placed under document management. The document management system should provide:

• A place to store each of the document, in a way that is easy for everyone who needs to find the documents
• The ability to store both baselined and working versions of a document, and a way to turn a working version into a baselined version
• A way to distinguished between versions of a document that represent work in progress and versions that are stable

A project should establish a document management system early in the initial concept phase. The concept will be represented in the artifacts listed below, and when these artifacts are reviewed and approved, a baselined version of each should be available in the repository.

32.7.2 Customer definition

Form. The customer definition document is generally a prose document; it does not need structuring the way objectives or requirements do. Some organizations may have customer relationship management tools that will capture some of the content defined below.

32.7.3 Customer objectives

Purpose. The customer objectives document is a record of what the customer wants out of a system. This document is a summary of what they have said they want and what has been drawn out from them in discussion or research. The objectives document is the source of all the rest of the artifacts developed for the system.

The objectives should record

• Who or what uses the system
• How the system behaves toward each of those users

The customer objectives document should be as close to the customer’s words and organization as possible. The document is a summary of the customer’s wants and needs. It is used as a proxy for the customer throughout system development, rather than having every developer talk directly to the customer to check their specification or design.

Other information must be kept out of the customer objectives document. The other information is captured separately in things like the regulatory and business objectives documents, which we discuss next. We have seen organizations include their business objectives, such as profitability, in the list of customer objectives. We have also seen teams include internal technical objectives like being able to reuse parts of existing designs included. Doing so creates confusion: is an objective in the document actually something the customer wants, or is this something the customer doesn’t care about? There will come times in the development process when hard decisions must be made about some part of the system design; at those moments, the team must be clear about what is actually a customer need and what is an internal need. If a customer need can’t be met reasonably, then the team needs to talk to the customer to resolve the issue. If an internal business or technical objective is proving hard to meet, the decision should be handled internally and the customer should not be involved—they don’t care or know about the issue.

32.7.4 Regulation and process definition

While the system being built needs to meet the customer’s needs, there are other stakeholders whose needs must be addressed as well. These are, broadly, internal objectives of the development organization and external objectives of third parties, such as regulatory bodies. Some of these objectives will define capabilities that the system must have. Other objectives provide constraints on how the system can function or be implemented, without defining specific capabilities.

32.7.4.1 Regulatory objectives

Many kinds of systems are subject to regulation. Some systems require licensing or certification, to prove that they meet regulations; others only need to be able to show compliance on demand.

These regulations pose constraints on the design of the system. Some are simple: aircraft emergency exits must be marked in particular locations. Some are complex: the crew of an aircraft must be able to properly determine what is happening with an aircraft even when there are complex failure situations—which involves human factors as well as the design of aircraft sensing systems.

A system will not be able to be put into operation unless it can meet these regulations. This means that the regulations must be incorporated into the design, just as the functional desires of the customer must be. One cannot do this unless one knows what the regulatory constraints are, and so one must search out and document all the regulations that apply.

The regulatory objectives document should at minimum list the source regulatory documents that apply to the system. Before design validation is complete, the information in the regulatory objectives document must translate into a detailed collection of requirements against which the system can be checked.

It is often necessary to involve either experts in the regulation of a particular industry or the regulatory agencies themselves to properly gather all of the regulations that apply.

32.7.4.2 Third party or service provider objectives

No systems operate in isolation. Instead, they operate within the context of a larger system of people, businesses, and organizations. This might include:

• Other systems that the customer already operates
• Services that the system will interact with directly, such as for maintenance or communications
• Services that the system will interact with indirectly, such as finance organizations that provide operating capital for the customer’s day-to-day operations
• Services or organizations that maintain the environment in which the system operates, such as a data center, an airport, or roads
• Part or component suppliers that provide components that will be used inside the system

The interactions and dependencies within this larger system also create constraints on how the system being designed must function. It is important to identify each of these organizations or systems, document how the system will interact with them, and then document the more specific objectives that are involved in working with them.

This information should be collected into one or more documents that record, first, the structure of the larger system and its interfaces with the system being designed; and second, the sources of constraints or objectives for each interface.

Information about the ecosystem in which the system will operate is likely to change frequently over the course of developing a system, especially for visionary projects. This means that it is important to update information about these objectives, and when it changes, flow those changes down into the system design.

32.7.4.3 Business objectives

An organization that is devoting resources to build a system must be able to obtain those resources. At the minimum, the organization must be able to hire and pay the people who design and build the system; it must be able to pay for the tools and prototypes it uses; it must be able to pay people to gather customer objectives and work with regulators and all the hundred other tasks involved.

Most organizations are also building an ongoing business, not just coming together long enough to build one system and then disbanding. Sustaining a business requires obtaining funding, getting sufficient return on the work the organization does in order to fund continuing work, and building capabilities that allow the organization to keep building or maintaining systems into the future.

All these imply that an organization needs to have a business strategy, which leads to business objectives. The organization may have a strategy of developing a product line that serves a wide variety of customers. This might translate into an objective to build a simple initial system product that is able to generate X revenue, and that can be extended over time to address the needs of more customers.

Many organizations develop these objectives at the executive level but do not feed the information downward explicitly to the team who must design a system. This is a problem because the design team knows that such objectives exist but don’t necessarily know exactly what they are, and thus can’t make accurate design judgments. We have seen, over and over, questions in a design team like “should we design this board with extra capability now, or design the minimal board and replace it later?” These have often led to arguments because the design team did not have the information needed to make a choice between a higher up-front investment cost for extra capability or incurring cost later in a redesigned board.

There are many different kinds of business objectives to document.

Some objectives are easily quantifiable:

• The budget for developing the system
• Deadlines for delivering the system and intermediate decision milestones

There are general business case objectives:

• The expected profitability of the system over time
  • The profitability of system development, if appropriate, or whether the development is purely an expense
  • How long it should take to recover development expenses
  • How profit or return on investment should evolve over time
• How the scale of the system should evolve over time
• How the size of the addressable market should evolve over time

Finally there are business strategy objectives:

• Is this project intended to build a single iteration of the system for a single customer? Or is it intended to be the base for ongoing development of an incrementally improving system?
• Is this project intended to produce other things of value besides the system itself, such as developing in-house capabilities in some area, or building technology or designs that can be reused (at low expense) in future projects?

These business objectives change continuously. When there is a proposal to change the objectives, the team must follow a disciplined process to determine what the effects of the change might be. This involves tracking down how the change will affect technical requirements and designs, which in turn affects whether the changes will affect the system’s ability to satisfy customer, regulatory, safety, or security needs. Changes to the design will also affect development cost and the time required to bring the system to operation. Sometimes a change to business objectives will make sense: changing the rate at which the system should scale up after the initial operational version may not affect the development time much but will increase customer satisfaction. Other times a change will have negative consequences: setting the goals for the size of the addressable market too high too early may require a higher development budget and longer development time than is available. Making a well-informed decision about these changes is only possible if the team can determine what the effects of a potential change in business objectives are.

32.7.4.4 Safety objectives

Safety is the condition that a system, when operated in the intended way, does not produce too many events that cause harm. There are four parts to this statement:

1. The operational system (its design and implementation)
2. The way it is intended to be operated (the intended functions and environment)
3. Produce too many events
4. Events that cause harm

In the end, a system must be shown to be safe by showing that the rate at which it causes harm is below a threshold. The process of designing a system to be safe is well known to be a difficult task, and there are many books and standards that try to give guidance on how to do so. As the system is designed, it must be evaluated to show the likely rates at which harmful events will occur.

This is a complex topic, and later chapters will address the design and analysis of safe systems. For now we focus on safety objectives.

Performing these evaluations requires defining what kinds of harms are to be measured, along with the acceptable rates at which they occur. There is no possible way to justify that a system is “safe” or “unsafe” without defining the harms they refer to.

A project, therefore, must define and document its high-level safety objectives in terms of the harms and the acceptable rates of those harms occurring. This is the safety objectives document.

Some industries have conventional definitions of harm and rates. The automotive industry has adopted a scale of zero to three for “severity” in the ISO 26262 standard ! Unknown link ref, focused entirely on injury to persons. Severity 0 is no injuries, 1 is light to moderate injuries, 2 is severe injuries with survival probable, and 3 is severe or fatal injuries. The aviation industry has defined a five-level scheme in the ARP 4754 standard ! Unknown link ref, ranging from minor (slight increase in crew workload or minor passenger inconvenience) through hazardous (serious or fatal injuries among passengers) and catastrophic (many deaths, loss of aircraft).

These two standards differ in two respects. They consider different ranges of harm: ISO 26262 has any severe or fatal injury as its highest category, while ARP 4754 considers the distinction between fatal injury and mass fatality. They also consider different kinds of harms: ISO 26262 only considers injury to persons, while ARP 4754 considers effects on the crew’s ability to control the aircraft and damage to the aircraft.

These point to deficiencies in the standards, and to the reason why a project should define its safety objectives more carefully. There are many harmful incidents that these standards do not address, such as damage to property, economic harm, or damage or injury to non-person cargo. Consider an incident involving a truck that damages an overpass, but does not injure anyone directly. The cost of repairing or replacing the bridge can run to several millions of dollars; the economic impact on the community of not being able to use the bridge can be equally high. In addition, depending on the industry, the range of severity in these standards can also be too limited: they do not account for harms that spread beyond the people and vehicles immediately involved in an incident. The use of aircraft as missiles in the 9/11 attacks showed how an aircraft safety incident can result in mass casualties or worse.

In addition to defining the harms that system design will consider, the safety objectives document sets targets for how often those harms can occur. Guidance issued for commuter aircraft ! Unknown link ref, for example, gives a maximum allowed rate of incidents per flight hour: XXX

Minor 10-3 Major 10-5 Hazardous 10-7 Catastrophic 10-9

The safety objectives document should define a maximum rate and the time interval over which that rate applies for each category of harm.

Some organizations may choose to say that the system they build should allow zero safety incidents above a certain level. This is possible only if the system can be guaranteed never to perform operations that could induce such serious events. For example, an aircraft can be guaranteed never to cause catastrophic harm, involving multiple fatalities—but only if the aircraft has a maximum weight of a few tens of kilograms, a low maximum speed before it disintegrates in the air, can only carry a single person, and so on. No transport aircraft (more than 19 seats or maximum takeoff weight greater than 19,000 lbs) that actually flies can ever have a zero rate of catastrophic harm. Similarly, many weapons systems can never have a zero rate of mass casualty harms simply because of the energy they carry. In most cases, as the conventional wisdom goes, the only way to get a system to have a zero rate of harm is not to build the system.

Safety objectives, like customer, business, or regulatory objectives, are sources that lead to the concept of operations and top-level system specifications.

Defining precise safety objectives early in a project is required for building a safe system. We have observed many projects that made aspirational statements about “safety being a first priority”. In every single instance where the definition stopped at that statement, the team designed an obviously unsafe system—often because, in the absence of an objective standard, each person took steps they thought would be safe but in aggregate the design missed even basic scenarios that resulted in hazards. Further, the absence of an objective meant that no one could perform an objective analysis of a design to determine whether it was good enough.

32.7.4.5 Security objectives

The security objectives document provides guidance for how the system should be designed and validated to ensure that it can handle a reasonable range of attacks.

Security objectives are similar to safety objectives: they define a set of harms resulting from security incidents that the system must work to avoid or contain. Unlike safety objectives, however, security incidents occur as the result of malicious, intentional actions rather than as a result of failures, accidents, or design flaws. Like safety objectives, the security objectives document names the harms that the system should avoid. It cannot, however, generally specify maximum acceptable incident rates because the rate at which attacks occur is something that attackers can deliberately control.

The approach to defining security objectives, then, is to name threat actors and the harms they can cause. A threat actor is a person or organization that can choose to initiate an attack on the system, such as a hacker, a criminal organization, or a hostile nation state. Each threat actor can be characterized by their motivations (a criminal organization for financial gain, a nation state to disable defense-relevant capabilities). The harms the threat actors can cause include disclosure of confidential information, interruption of business, death of persons, financial loss, or theft of goods. The list of harms includes every kind of harm addressed as a safety concern, plus harms that do not involve damage or injury but do involve loss of value or information.

The system must then be designed to address the different harms that different threat actors might pose. The resulting design can be analyzed to determine whether the threats are sufficiently addressed. The built system can be tested to verify that key defensive features are working as intended.

The definition of “sufficiently addressed” remains subjective. Some security analysis techniques have rationales for assigning weights to different threats. For those analyses, ensuring that all high- and medium-priority threats have been mitigated might be sufficient.

There are many standards related to security, and depending on the industry and geographic region compliance with some standards may be mandatory. These may define security objectives that a system must meet for regulatory or business acceptance. This information should be documented in the regulatory objectives document, and information about threat actors or harms should flow from the regulatory objectives document into the security objectives document.

32.7.5 Concept of operations

Purpose. The concept of operations (CONOPS) document is the systems team’s response to the customer’s objectives. It collects in one place a description of how the system will work, from the point of view of the people who will use it. Whereas the customer objectives come from the customer and should record their needs from the customer’s point of view, the CONOPS shows how a system could behave in a way that meets the customer needs. The CONOPS is written from the point of view of the system.

The CONOPS document organizes the ideas about how the system will behave. In doing so it gives a model for understanding how the system’s functions can be organized and how different behaviors relate to each other. It does not aim to provide every detail about the behavior; its value is in documenting the big picture.

The CONOPS document has three primary purposes:

1. To collect a description of the system’s behavior in one place, which can then be used as the source to develop the system’s specification and design,
2. To provide a description of the big picture for how the system will work to people on the team, especially people joining the team, and
3. To feed back to a customer the system’s team’s understanding of what the customer has asked for, in order to check that understanding.

The document is typically written as a narrative, and not as formal requirements or detailed behavioral models. Its value is in its explanation, not its precision. It is an explanation of how the system might function, without reference to how the system can be implemented to achieve those functions. The details of operations, as well as the implementation, are recorded in documents that derive from the CONOPS. It should, however, expose the users, features, functions, states, and use cases that model what the customers’ objectives mean.

The CONOPS should include functions that are implicit in the customer’s objectives. For example, the document should cover the system’s entire life cycle, from deployment or initial startup through shutdown and disposal. The document should cover major faults that might occur, and the system’s behavior when those occur. For a spacecraft, for example, it should include recovery modes that allow the spacecraft (perhaps under ground control) to re-establish normal operation after a fault. It should include not just the technical core of the system, but also how the human or organizational elements that use the system behave. For an automobile, the CONOPS should not just say that there is a driver, but include expectations like the driver being trained and licensed. For an airline, the CONOPS should include the airline’s safety management system and how that interacts with an aircraft or maintenance technician.

To produce the concept, the systems team reviews and understands all the objectives documents already described, then follows a process to extract from those objectives a model of how a system could behave. The process of analyzing all the objectives will almost always reveal things that the customer or others have not addressed—customers often focus on the main operational behaviors, for example, and don’t address how to deploy or dispose of the system. The systems team needs to find these gaps and address them. Where possible, the systems team should work with the customer to check whether the customer in fact has expectations about these topics before committing to a concept.

32.7.6 Reviews and approval

Purpose. The initial concept development phase gathers and organizes information about what a system should be and how it should behave. It gathers this information from many sources: the customer (if there is one), third parties that impose constraints, the developing organization’s policies and standards.

The concept leads, in turn, to all of the technical artifacts that make up the system and its design: the specifications, designs, analyses, implementations, and so on. Those technical artifacts can only be as good as the concept from which they are developed, so checking that the concept is accurate and complete is vital to producing a good system.

The team is ready to proceed to system specification when two conditions hold:

• The team is confident that the system concept is complete enough and that it accurately reflects customer objectives
• The team’s organization is confident that the team can do the work. This means that the organization has the resources and skills to do the project; that the project is in line with the organization’s business strategy; and that the project is well enough defined to be confident in these evaluations.

32.7.7 Proposal (RFP-driven projects)

Purpose. A proposal, in the sense meant here, is a document that is sent to a potential customer in response to a request for proposal (RFP) that the potential customer has issued.

A proposal needs to make four cases to the customer:

• That the team has a technical solution that meets the customer’s needs
• That the team has the capability to actually produce the system
• That the price for the system will be acceptable
• That the team has a better offering than its competitors, if any

The proposal derives from the work done during concept development, but usually also must include initial system specification and design work. This initial technical work is needed both to be able to explain to the customer what they would be getting if they choose this team to develop the system, and to generate a reasonable price for building the system.

Many processes and guidelines for proposal development have been published over the years, and we refer the reader to that large body of literature for details.

32.7.8 Competition documentation

Chapter 33: Specifications

33.1 Purpose

Specification is about recording how a component (or system) should behave or the structure that the component should present. It only documents how the component appears from the outside, as a black box; it does not specify how the component achieves these ends. A specification derives from the less-formal concept for the system or component.

XXX address specification vs requirement

XXX make sure this ties into the broader flow of phases

A specification provides a simplified and abstract view of a component. This abstract view allows one to reason about how the component will work with other components. Without the abstract view, one would have to analyze the details of a component’s implementation to determine whether it will interact properly with another. While that is possible, the work of figuring out how the component will behave only serves to reconstruct design information that was originally worked out when designing the component. The reconstructed information will not necessarily match the information used during design, and the effort is wasteful.

A good specification records the intent and assumptions that went into working out what the component is supposed to do. This information helps the component’s implementer and designer to check that they understand what they need to build, and to check that the specification matches the intent. These assumptions also help people understand how a component might need to change when part of the system is redesigned—to add a new feature, for example. A record of the intentions helps people who come along later to understand the system, and the particular component’s role in it.

Finally, a specification serves as a sort of contract between a component and the rest of the system in which it functions. The people building the component in question can proceed to work on their component with confidence that the result will likely integrate correctly into the system as long as they build to that contract. The people building other parts of the system can likewise proceed with reasonable confidence that when they go to use the component, it will do what they expect.

33.1.1 Good specification properties

A specification is used for several different tasks by different people over the course of a project. A good specification needs to be structured and contain the information needed to support these people.

Specifications should be clear and unambiguous. Each of the people who will read and use each specification need to come to the intended meaning of the specification.

They should be testable. Someone using the specification should be able to look at a design or implementation and determine whether it is compliant with the specification. That does not mean that determining compliance is easy; it only means possible. Sometimes the most that is possible is to build a body of evidence that a design is highly probably compliant. For a specification to be testable, however, the specification can’t contain statements like “approximately” or “fast” or “heavy”; it needs specific values that define what “approximately” (“+/- 10%”), fast (“at least 20 m/s”), or heavy (“greater than 5 kilograms”) mean so that compliance is not a matter of subjective judgment that can differ between two different people.

The specifications need to be organized. A specification is no good if the people who need to use it don’t know it exists or can’t find it. A specification is also not useful if the people who need it can’t tell whether it is currently applicable, outdated, or a speculative proposal. Specification should be kept in one place where everyone on the project can find all of them, and they should be maintained under configuration management.

A good specification is minimal. It addresses the needs for the system or component that have been identified in the concept work leading up to the specification, but it does not add other elements that are not relevant to the identified needs. (Note, however, that the process of developing a specification can often reveal needs that were missed in building up the concept and CONOPS. When those gaps are found, the concept and CONOPS need to be updated as well as addressing the gap in the specification.)

33.1.2 Specification versus documentation

Specification and documentation play different roles. Specification is a record of what something should be, while documentation is a record of what it has been designed and implemented to actually be. Specification deals with the black-box, external behavior, while documentation deals with the internals of the component. The documentation should connect decisions about the component’s internal structure to the external behavior or structure documented in the specification.

33.1.3 Specification needed to scale a project

A small project, implemented by a very small group of people over a short time and thereafter left alone, and that does not provide safety- or security-critical functions, does not necessarily need specification.

Unless all of those conditions hold, some level of specification is necessary in order to communicate between people and across time.

The communication includes:

• Between those who design the system at large and those who design and implement a specific component. The specification allows different people to work on different parts of the system, which in turn allows a larger team to do the work, and allows some of the work to proceed in parallel.
• Between those who design and implement a component and those who verify its correct behavior. The specification defines the “correct behavior” that verification checks.
• Between the original designer and someone who must adapt part of the system later (for a new feature or to fix a problem)—bearing in mind that those may be the same people, but later in time when the details are likely to have been forgotten. The specification conveys a simplified, abstract version of what a component is supposed to be, so that the designer making changes can work out how the behavior should change and so that they can work out whether the changes will likely integrate correctly to address the new feature.
• Between the system designers and implementers and those who later inspect the system as part of safety or security incident response. Accident response relies on being able to reconstruct both what happened in an incident and what was supposed to happen. This reconstruction is part of determining what changes need to be made to ensure that similar accidents do not recur, and it is also part of working out how to repair things after an incident (when that is possible).

33.2 Specifications and systems

A specification defines the metaphorical shape that the component should have in order to fit into and support the system.

A specification treats the component as a black box: it considers only how the component should be seen from the outside, without determining how the component’s internals should be designed or implemented. One way to look at the specification is that it defines a contract between the system and the component: if the component behaves according to the specification, the system should work correctly as a whole.

A specification may define behaviors or attributes that in effect narrow the range of possible designs, possibly to only a single design. That situation in itself does not make a specification invalid. However, the specification should not include definitions that are not strictly needed to record needed external behaviors solely in order to constrain the design.

After a component has been specified, design of the internals of that component begins. The internal design often uses sub-components. The designers will develop specifications for the sub-components.

This process repeats recursively to lower and lower components, until one reaches components that have no further sub-components. The result is a tree (or possibly a DAG) consisting of alternating layers of specifications and designs. (This has been called the “layer cake model”.) The design of one component (or the system) responds to its specification. The specification for subcomponents depends on the design that has been selected for the component—the design determines both what subcomponents there are, and how they are to work together.

33.3 Example

Some years ago, I worked on a rack-mounted computing system that had high reliability and uptime goals. A decision was taken to include a battery pack in each server assembly, so that if the mains power went out the servers would have enough time to record their state on storage before shutting down.

Consider the specification for the battery pack. It may seem simple—provide enough power to run the server assembly for some period of time—but the actual specification contains several subtle elements because its function is entwined with other system-wide reliability and safety behaviors.

Here are some of the system behaviors that affect the specifications for the battery pack:

• Keep the server assembly running for long enough to save state to storage and perform an orderly shut down
• The server assembly must be able to change its behavior when the battery pack does not have enough energy stored to safely shut down
• A server assembly should function correctly for at least X years before needing replacement
• When a server assembly is developing a condition that suggests a component will fail soon, the server should detect the likely failure and initiate a repair call
• The server assembly must be safe and convenient for a customer to assemble (if needed) and install
• The server assembly must not cause a fire, release toxic gasses, or cause other similar harms (which references a safety standard defining the harms to be avoided)
• The server assembly must not be vulnerable to supply chain attacks, such as substituting unapproved components, in the period between manufacture and installation at a customer site
• The server assembly must fit into a standard 19” computing rack (which references a mechanical standard specification)
• The server assembly is intended to operate in a data center environment (which references an environmental specification)

These are rough objectives for the server assembly as a whole. These translate into specifications on the battery pack itself.

Addressing keeping the server assembly running:

• The battery pack must provide power at X volts and Y current for at least Z minutes when mains power stops providing power to the server assembly
• The voltage and current must be maintained within X of these reference values
• The battery pack must provide connectors to deliver and receive electrical energy to and from other components in the server assembly

Addressing the server assembly changing its behavior:

• A management system attached to the battery pack must be able to determine when the battery pack state of charge is sufficient to meet the voltage, current, and time need, and when the state of charge is not sufficient ⇒ The battery pack must provide information that allows accurate estimation of its state of charge (e.g. having an accurate relation between voltage and state of charge)
• A management system must be able to account for temperature and battery age in making this determination ⇒ The battery must have predictable changes in behavior as temperature and age change

Addressing the server assembly lifetime:

• The battery pack must not degrade its storage capacity more than X% over Y years
• The battery pack must support a management system detecting when the storage capacity degradation is approaching a level when battery pack replacement will be needed

Addressing likely failure:

• The battery pack must exhibit behaviors that allow a management system to detect degradation or incipient faults, such as failure of one battery cell or overheating
• The battery pack must have identification that allows batteries from the same manufacturer and manufacturing lot to be tracked for common failure patterns

Addressing safe and convenient customer installation:

• The battery pack should be shipped discharged
• The battery pack should be safe to handle without protective equipment as long as its case or assembly is not damaged or modified
• The battery pack should not make the server assembly too heavy for one person to lift safely
• The battery pack, if separately installable, must not have error-prone cabling that a customer might hook up the wrong way

Addressing fire, toxic gasses, and similar safety issues:

• The battery pack should be sealed against emissions up to at least X internal pressure
• The battery pack should be able to handle up to X impact without taking damage that would lead to thermal or mechanical failures
• The battery pack should provide sufficient information to a management system that the management system can disconnect the battery when a failure is beginning, and so that the management system can trigger external safety systems

Addressing supply chain attacks:

• The battery pack must be handled only by trusted employees and agents of the company from manufacture to installation
• The battery pack must include identifying information that is hard to falsify or replicate

Addressing fitting into a standard rack:

• The battery pack must weigh no more than X kilograms
• The battery pack must occupy a volume no greater than X by Y by Z millimeters
• The battery pack must connect to the rest of the server assembly using X brackets

Addressing the environmental conditions:

• The battery pack must function nominally in a given temperature, air pressure, humidity, air gas composition, and dust environment

These example objectives are not all of what would be needed for a server battery pack, but they illustrate several of the kinds of concerns that the battery pack’s designers will need to consider. These rough objectives must be turned into more precise specifications in order to guide the designers accurately. For example, some of the statements above use subjective words like “nominally” that need to be made precise. Other statements are too general and need to be decomposed into a set of more specific statements.

33.4 Kinds of specifications

“Specification” is a deliberately broad term, encompassing many different ways of recording what something should be or do (and why).

Many people assume that “specification” means “requirements”. While requirements are one kind of specification, they are not the only one—and requirements are not generally sufficient by themselves to record all the information needed about behavior or structure.

Kinds of specification include:

• Scope or environment. This is a specification of the boundary for a component (or system) Section 6.3 and, therefore, what is inside and outside of the component (or system). The nature of the environment can be seen as a statement about interfaces, it is usually a good idea to document this explicitly. XXX say more about scope below
• Requirements. These are short prose statements about what is expected of the component. These statements have the advantage that they have all the flexibility of written language. A reader only needs to know normal language and the associated technical jargon to understand the meaning of the statement. Requirements also have the advantage that they are easily organized and identified in an outline or table form, so that one can trace through each individual statement. Requirements inherit the disadvantages of written language that lead people to devise other notations or diagrams.
• Interfaces. While a specification is in general a definition of the overall interface between a component and the system around it, in many domains part of the specification is gathered into an interface (often recorded in an Interface Control Document). A software application programming interface, which defines data structures, function calls, and communication steps used to communicate with a component, is one example. An environmental specification is another example that specifies the heat, vibration, atmosphere, electromagnetic radiation, dust, and other environmental conditions that a component must handle correctly.
• Models. These are (semi)formal expressions about structure or behavior, written in a specialized notation or diagram. These expressions have the advantage of being able to express needs that are not easily expressed in prose, such as physical or temporal relations, or mathematical statements. These have the disadvantage that readers often have to learn new notations in order to understand what the expressions mean. Many notations do not lend themselves to easy enumeration of each individual condition that the component should comply with.

There are many kinds of models.

• Mechanical models show the physical interface that the component should support. This can be as simple as a volume in which the component must fit. It might include connectors for how the component is attached to other components in the system. More advanced models might include the forces that may act on the component, and how the component must pass those forces from one place to another, or how a component may deform in response to forces.
• Mathematical models document how a component behavior should respond to outside inputs, expressed as mathematical formulas. This can range from a simple linear response to an input to a complex and stateful impulse-response model. Many of these are expressed on a continuous time domain.

• Behavioral models document how the component will perform sequences of output actions in response to inputs. Many of these models are expressed as diagrams: state machines, sequence or activity diagrams, or timelines. Some models, such as state machines, express all the possible sequences of behavior that could happen; other models, such as sequence diagrams, express one or a few specific sequences without being exhaustive. Many of these models operate on a discrete time domain.

• Domain-specific models. These express needs that are specific to some problem domain, and that are not easy to express in one of the other kinds of models. For example, Earth-orbiting spacecraft typically have an orbit specification, which can be used to determine where the spacecraft will be at various times in the future and what the conditions will be at those times. A material specification might include parts of the phase diagram for the properties of the material at different temperatures and pressures, indicating some conditions in which the material must be solid or gas. Most domain-specific models have an underlying mathematical definition, but the needs can be expressed more clearly using the domain-specific notation rather than only using the underlying formulas.

33.4.1 Combining multiple kinds of specification

In practice I have found that no one kind of specification meets all needs, and have used multiple kinds of specification together.

Generally, each kind of specification we use meets the good specification objectives of being clear and testable, as defined earlier.

Mixing multiple kinds of specification, however, requires care in organizing the specifications. Different kinds are often written and stored in different tools (a tabular tool for requirements; a CAD tool for mechanical drawings). This easily leads to a situation where a practitioner cannot find all of the specifications to which they need to be paying attention.

One way we have addressed this is to use a table of textual requirement statements as a primary specification, and include requirements like “the component shall comply with state machine X”, including a reference to the drawing of the state machine. Using a tool that makes all these forms accessible through one common user interface helps make this convenient for users. Using tools that can perform configuration management across all the different forms of specification also helps.

33.5 Using specifications in a system

We first look at how specifications are developed and used from the outside: from the perspective of those who are concerned with how a component fits into the system, and not with what the specification means for the design internal to a component.

A specification for a system derives from the objectives and CONOPS developed during the system concept development phase.

The system-level specification leads, in turn, to a system design and then recursively to the concepts and specifications for components in the system.

33.5.1 Building the specification

This is the first step in using specifications. The specification developer looks through all of the conceptual material assembled for the system or for a component, and organizes and formalizes it to make a specification.

In practice this does not happen all at once. People develop the various kinds of objectives that lead to the specification iteratively, and parts of the specification will be developed as the objectives and concept becomes clear. As people develop the specification, they will identify gaps in the concept, which will lead to improvements in the objectives and CONOPS and in turn lead to updates to the specification.

33.5.2 Evolving the specification

The needs that a system solves change over time. New capabilities get requested. Regulations evolve. Problems with the system are found and need to be fixed. All of these can lead to changes in the concept and thus to changes in the system specification.

The concept and design of components also changes, and for similar reasons. As well, a component may have a perfectly adequate design, but it may become outdated because subcomponents become unavailable. This leads to a redesign of a component, inducing new specifications for subcomponents.

It is important to follow an organized process when a specification changes. Many process standards recommend specific approaches; for example, ISO 26262 [ISO26262] specifies that any change to a system must begin with an impact analysis, which determines how a change to objectives or specification propagates through the design of the system, and downward through the hierarchy of components. Standards like that also specify that the specifications and designs be maintained under configuration control so that everyone can know whether a change is a work-in-progress proposal or has been committed to.

33.5.3 Validating the specification

The specification must reflect all of the needs identified in the concept from which it derives, and the specification must not add needs that do not appear in the concept and objectives. Before a specification can be declared complete, someone must go through all the material in the concept to check that the specification accurately reflects each of the identified needs or objectives.

A specification validation exercise can also help identify gaps in the objectives. Checking the specification often involves someone who was not part of developing the objectives and CONOPS; a fresh perspective can lead to asking questions about the objectives or the specifications that in turn lead to discoveries of topics that are missing.

33.5.4 System consistency

As the system design grows and more and more components are defined and specified, someone needs to check that the designs and specifications are all consistent. This is especially important for “long distance” dependencies: where the correct function of one component depends on the correct function of another component in a different part of the system. (More formally, when two components A and B depend on each other for correct function, and the lowest common parent of A and B in the component hierarchy is near the top of the hierarchy.)

33.5.5 Safety and security design

As we will discuss in future chapters ! Unknown link ref, the safety and security properties of a system must be designed top down, and they need to be defined early in system development, before too many low-level components are designed.

We advocate using the systems safety methodology ! Unknown link ref, which emphasizes starting with the accidents or losses that are to be avoided, and then the conditions that must be maintained in a system to achieve safe operation. (This is different from many safety methodologies, such as functional safety, which focus on safety in the face of failure conditions and do not address safety problems arising from design or component interactions.) The categories of losses come from the safety and security objectives defined in the concept development phase.

Some example conditions:

• A spacecraft must not perform any propulsive maneuvers, emit radio frequency radiation, or perform any physical deployments within 1 km of the upper stage vehicle from which it was deployed. (This example is based on real launch vehicle safety requirements.)
• A planetary lander must maintain engine thrust until it has touched down on the surface. (This example is based on the accident analysis of the Mars Polar Lander spacecraft; see ! Unknown link ref for details.)
• An autonomous aircraft must not take operational commands from an unauthorized source.

Once these conditions are identified, systems engineers must determine how to address them in the design of the top-level system. They must then create derived specifications for each of the top-level components in the system, and show that if each of the components meets its specifications the overall system will exhibit safe or secure behavior by complying with the safety and security conditions. This process is repeated through at increasingly lower levels of the system.

33.5.6 Review and approval

A specification guides the design and implementation of parts of the system. Given the importance of this role, a specification—or an update to a specification—should be reviewed before being committed to. Each specification should be checked by the people whose work it affects: system designers, the designer of the component or system that contains the thing being specified, potential implementers, and those people who are working on components that will interface with or use the component being specified.

As with other system artifacts, a specification or specification update should be under configuration management so that each user can determine whether they are using the correct version or not, and whether the version they are using is a proposed or work in progress version, is the current approved (baselined) version, or a version that has become obsolete.

33.6 Using specifications for a component

We now turn our attention to those people and activities who use a component to design and implement a component; that is, who are concerned with how the internals of a component reflect its specification.

There are two tracks of activity that use a component’s specification:

One track follows the design and implementation of the component itself, which should result in a component that complies with the specification. The other track follows the design and implementation of verification methods, such as tests or static analyses. The tracks come together when the implementation gets checked by the various verification methods, resulting in a determination of whether the implementation is in fact compliant, or whether the design and implementation need to be fixed to bring it to compliance.

33.6.1 Learning about a component

A specification is an abstracted view of what a component should be. That makes it useful as a guide for someone who needs to learn about a component, before diving into the design or implementation of that component.

Someone who is learning about a component—or about the structure of the system across many components—needs to be able to find the relevant specifications. The specifications should be organized to support them:

• Components should have names or identifiers
• Specifications should be stored in a repository that allows people to find a specification by its component id, or be able to navigate through the structure of the system to discover information about components
• Users should be able to start their search in a single place, well-known to all the team, without having to discover multiple tools that might or might not be readily apparent to new team members

33.6.2 Designing and implementing to specification

The general task of a designer or implementer is to create a component that complies with its specification. In practice, of course, this is a complex activity.

The designer needs to be able to clearly identify all of the behaviors or capabilities that the component must implement. This implies that the specification must be organized in a way that helps the designer find all of these, and in a way that can serve as a checklist for tracking which features have been satisfied and which have not yet.

As we will discuss further in upcoming chapters, the designer or implementer should be able to identify which aspects of the component have the highest design risk or are the most technically complex. The designer and implementer will often choose to focus on these hard aspects first, before dealing with aspects that are easy to solve. The hard aspects are often candidates for prototyping, in order to determine if a design approach is feasible and can meet the specification. (See XXX for more on prototyping and risk reduction.)

Complex systems and components can benefit from the combination of incremental development and continuous integration. Incremental development involves selecting a few parts of the component’s specification and implementing those, followed by testing. Once those aspects of the component appear sound, the developers perform a second iteration by selecting a few more aspects of the specification and adding them to the design and implementation. Continuous integration, in this context, involves performing integration testing of these partial designs and implementations in a skeleton of the rest of the system. The partial implementation of this component may use mockups of subcomponents, or interact with mockups of peer components in the system. We discuss incremental development and continuous integration more in XXX.

As people work through design and implementation, they are likely to find problems or gaps with the specification. The specification may be ambiguous in some part, or the specification may not define the behavior for some condition. The developers must be able to work with those who defined the specification to sort out these issues. The developers should check the specifications in depth, asking the specifiers questions to check their understanding or to confirm that there are issues. The developers then should work with the specifier to resolve the issues.

The developers should not make an assumption about a gap or ambiguity and move forward without confirming their assumption. The people who wrote the specification are responsible for ensuring that the specifications for different components are consistent and address large-scale safety or security concerns. The behaviors needed to support correct interaction are encoded in the specification. The developers are responsible for implementing components that correctly support these behaviors so that the resulting system works correctly. The developers do not necessarily have the big-picture perspective to make changes to these critical behaviors, and do not necessarily know who else needs to know about an assumption in how a component is defined. The developers need to work collaboratively with those responsible for the specifications so that all the pieces of the system remain consistent and correct, and so that everyone involved shares a common understanding of how the components and system are to function.

A component’s implementation will need to be verified against the component’s specification. People using continuous testing or test-driven development methods have had good results producing correct component implementations efficiently by testing an implementation in small increments as functionality gets added to it. This reduces the risk that the design or implementation has made some fundamental, early mistake that becomes increasingly expensive to correct as more functionality is implemented on top of the erroneous implementation. Performing continuous testing (or verification) requires having verification cases defined and implemented concurrent with the implementation of the corresponding functionality.

Finally, each component design and implementation will need to be reviewed and approved before being accepted as finished. Verifying that the design and implementation comply with the specification is a major part of the review process. The review activities will be much easier if the specification is well organized.

33.6.3 Evolving specifications

As mentioned earlier, a component’s specification will likely change when a system remains in use for a long time. Systems engineers will need to investigate the impact of making a change to a specification before committing to the change.

The component designers and implementers are part of the investigation process. While a systems engineer can look at what will change in how a component interacts with other parts of the system, the component designers and implementers are better positioned to evaluate the effect that a change in specification will have on implementation or verification.

To change a design and implementation in response to a change in specification, the developers need to correctly determine what has changed in the specification. Having a clear mechanism for showing what requirements have been removed, added, or changed, and for showing specifically how other parts of the specification have changed, makes this task possible. In particular, being able to accurately enumerate every change is important; the developer should not have to hunt for subtle changes that may be hidden.

The decisions that are encoded in a component’s design include how different parts of the component interact with and depend on each other. When a component’s design is to be changed in response to a change in specification, some parts of the design will be directly affected. For example, a decision to add a new input message to a component directly implies that new message reception and handling functions must be implemented. However, one change can affect other parts of the existing design, and the designer and implementer must find and address all of these effects. The example new input message, for example, might require changes to a database schema for storing additional information, or might affect response time behaviors that require changes to foundational concurrency control capabilities in the design. Having a clear record of how parts within one component are designed to depend on or affect each other reduces the effort involved in making this kind of change, and reduces the chances of an error stemming from some dependency being overlooked.

33.6.4 Verifying a component

The specification defines what a component should be or do; the design and implementation define how it is or does these things. Verification is the process of ensuring that the implementation produces behaviors that match the specification.

Every element of the specification should have a corresponding method for verifying compliance of the implementation. Different aspects of the specification will require different methods: some aspects can be verified by testing, such as showing that given some input A, the component responds with behavior B. Other aspects will require demonstration, such as showing that a physically representative user can see and reach control devices. Some aspects—especially safety and security—can only be verified by analysis or formal methods, such as showing that a component never enters performs some action identified as unsafe.

Verification methods involve design and implementation, similar to the design and implementation of the component itself.

Designing a verification method involves, first, determining how a specification property can be verified. (Sometimes a property is best verified using more than one approach in parallel.) once the approach—testing, review, demonstration, or analysis—has been determined, the next step is to design how that specific specification property will be checked. That can involve designing a set of test cases that cover the expected behaviors, or defining a test procedure to evaluate a mechanical component, or defining who will perform a review and what they will look for.

Implementing a verification method turns the design into a specific set of tools and actions that, when used, give a yes-or-no answer to whether the component is compliant.

The verification methods can have errors. Indeed, in some cases the verification of a property can be more complex than the component implementation it is checking. This means that the verification designs and implementation need careful scrutiny to ensure that they are, in fact, checking the specified properties and not something else.

The verification methods also must be complete: if some property is worth specifying, it is worth verifying. The verification designs and implementations need to be checked to ensure that they cover all of the specification. Explicitly recording which parts of the specification any particular verification method checks helps the task of checking completeness.

Finally, it is common for project management to track what portion of a component’s specification has been completed and verified. This can be organized by identifying each property in the specification, and tracking which verification methods check each one. As verifications are done, the project managers can determine which parts of the specification correspond to verification activities that passed.

33.7 Specification artifacts

Specification activities take as input the objectives ! Unknown link ref and CONOPS ! Unknown link ref artifacts that were generated during concept development.

The specifications themselves involve:

• The component breakdown structure ! Unknown link ref, which organizes the components that make up the system and define the entities that will have specifications written for them
• For each component, some kind of index or table of contents that organize all the elements of the specification for that component
• Tables of requirements ! Unknown link ref, interface definitions ! Unknown link ref, and models ! Unknown link ref that make up the specification

The elements in the specification should include traces that show how each individual part of the specification derives from some part of the objectives or CONOPS, and conversely how each part of the objectives is reflected in the specification.

The specification artifacts should be maintained under configuration management. That means that there should be a common repository that everyone working on the system can use to retrieve (and potentially update) the artifacts. The repository should maintain separate versions of each artifact, and clearly identify which version is the current, baselined version that people should use, which versions are outdated, and which are works in progress.

The configuration management system should support people reviewing a specification, and must support recording when a particular version has been approved to be baselined.

Chapter 34: Requirements

34.1 What are requirements?

Requirements are one kind of specification: they say something about a property that a component or system should have, or a behavior they should exhibit.

A requirement is a specification in the form of a single, declarative textual statement. In the simplest case, a requirement is a statements of the form:

For example,

There are many nuances and variations on this basic form, but they are all extensions of this basic idea.

Requirements are written this way in order to maximize the simplicity and clarity of the specification.

Requirements are only one part of the specification for a component or system. They document specific facts about a system’s design, but they do not document the explanation of how that particular design came to be. They do not document the general purpose and scope of a particular component. They do not document complex interaction patterns. These other parts of a specification are documented in other design artifacts that complement requirements.

34.1.1 Why write requirements?

One of the jobs of systems engineering is to ensure that a user or consumer of some artifact (system or component) will be satisfied with the artifact once it is built and deployed.

The specifications for a system or component serve as a way to organize the information about what the user wants, and to organize the process of checking that the final result meets the user’s desires. The specification thus acts as a kind of implicit contract between the end user and the implementers: if the user agrees that the specification properly records their objectives, and the resulting system can be verified to meet the specification, then then the implementers have built something that satisfies what the user agreed to. (Whether the user is actually satisfied is a separate matter.)

XXX would a couple diagrams help here? A first one might show user → conceptual artifact, conceptual artifact → developer → concrete artifact; a second one might show systems and verification in the picture?

This means that there are three main uses for requirements (and the rest of specifications):

1. Encoding the user’s objectives in a written form, and allowing the user to validate that the specification matches what they want.
2. Guiding implementers as they work out the design for the artifact that will meet the user’s objectives.
3. Providing a checklist for verifying that the resulting artifact meets the specification, and thereby the user’s objectives.

A systems engineer is typically the keeper of the specifications, responsible for overseeing the writing, changing, and verification of requirements and other specifications.

Requirements—and all specifications—are therefore acts of communication between multiple groups of people with different roles in building the system.

Systems engineers are facilitators and interpreters in this communication between users and implementers. They are responsible for translating information received from users into specifications (including requirements), for explaining the specifications back to the users for validation. The information from the user is often unstructured and incomplete. It is up to the systems engineer to work with the user to clarify their objectives and ensure that the result accurately reflects the user’s intent. The systems engineer also works to ensure that the specifications are complete. This often involves identifying use cases that the user has not thought of themselves and working with the user to define what behavior the system should have in those other cases.

The systems engineer also facilitates the implementer’s work. The systems engineer develops specifications so that the implementer has a clear guide to what they need to design and build; this requires that the systems engineer provide translation or explanation when the specification does not use the same terms or concepts that the implementers do. The systems engineer is also responsible for ensuring that the final artifact meets the customer’s objectives by overseeing the verification of the implementation against requirements (and other specifications). This involves working with verifiers to ensure that verification methods match the requirements, and checking that all requirements have been verified before the system is declared done.

A systems engineer performs other tasks using requirements, such as checking consistency or completeness. We will discuss these tasks in a later section.

A good requirement must meet several objectives in order to provide accurate communication between all these parties:

• A requirement must be unambiguous. Each of the parties must be able to read the text of a requirement and have the same understanding of what it means.
• A requirement must have an unambiguous meaning about the system.Two people should be able to look at the system and read the requirement, and come to the same conclusion about how the system is supposed to behave if the system meets the requirement. Many people express this as “a requirement must be verifiable”.
• A requirement must be accurate. A requirement that misleads a reader has no point.

These needs lead to conventions about how requirements are written and organized, as we will discuss later.

34.1.2 What are requirements about?

Requirements are a general-purpose way of writing down facts about what something is supposed to be (or not be).

Requirements can apply to just about anything. In a typical system project, they will be used to:

• Record the objectives that end users have for the system as a whole
• Record the regulations and policies that people governing the system
• (or its market) impose on systems like this
• Record the behaviors and properties that individual components need
• to have on order to fit together into the system as a whole
• Record the processes that the system’s implementers must follow
• while building the system
• Record elements of the contractual relationships between the
• system’s implementer and vendors that supply parts or services
• Record policies for the behaviors required of people working with the system

34.1.3 The context for requirements

Requirements don’t stand on their own.

Most requirements in a system will apply to particular components in the system. The component breakdown structure provides the list of components that requirements can be about.

Requirements are part of more general specifications for the system and its components. The specifications include

• A definition of the scope and purpose of each component
• The structure of how components connect together to make up the system
• Analyses of the system design, such as fault trees or performance models
• Specifications of behaviors that cross many different components

The requirements must be consistent with these other parts of a component’s specification.

In the end, requirements are satisfied by the implementation of the components in the system. Being able to trace the connection from a component’s requirements to the pieces of the implementation matters in order to be able to show that the requirements are satisfied.

34.2 A single requirement

A requirement itself is a single statement about something that should be true about something.

More formally, a requirement has three parts:

• A subject, naming what thing the requirement applies to. The subject can be the whole system, a part of the system, or sets of parts.
• A mode, naming the relationship between the subject and the properties. A word like “shall” or “must” is the most common mode, indicating that the property must be true or shall be true about the subject.
• A property, encoding a predicate that is to be true about the subject. This can be just about anything, as long as everyone involved can agree on what it means for the property to be true. It can describe a behavior that the subject should provide, or some characteristic that the subject should maintain. The property is usually written as a verb followed by the object of the property, such as

where “be placed” is the verb.

Some examples:

• The spacecraft shall have a mass no more than 1 kilogram
  • Subject: the spacecraft as a whole. The spacecraft is made up of many subcomponents; this requirement applies to all of them put together into the complete spacecraft system.
  • Mode: shall—this is something that we require to be true.
  • Property: have a mass no more than 1 kg. This is a measurable property of the spacecraft; once assembled, it can be put on a scale and checked.
• The electrical power subsystem (EPS) must provide a minimum of 25 W in standby mode
  • Subject: the electrical power subsystem. This is a named subsystem within a spacecraft.
  • Mode: must—this is something that we require to be true.
  • Property: provide a minimum wattage when in a particular mode. This is a conditional property: it only applies when the EPS is in standby mode. For this property to be meaningful, the design of the EPS must include a set of modes, and “standby” must be one of them.

34.2.1 Example

Consider an example of a statement of what the mission manager for a small spacecraft mission wants:

This sentence has a number of problems. It mixes statements together: the mission and the spacecraft, the operating environment and the lifetime. The sentence is not very precise: what is “low Earth orbit”? What does the spacecraft have to do to “operate”? It is unachievable: nobody can guarantee that a spacecraft will function for a particular duration as an absolute guarantee; what if there is an unusual solar flare that fries its electronics?

We can improve the example sentence a bit by splitting it into three requirements statements:

• The mission shall operate a small spacecraft
• The spacecraft shall operate nominally for at least three years with 95% probability
• The spacecraft shall operate nominally in low Earth orbit between 200 and 400 km altitude

These requirements improve the original statement. First, it splits the original so that each requirement is about a single topic (and is written in the subject-mode-property form). Second, it improves the description of two of the requirements by making them more achievable (“95% probability”) and precise (altitude range given).

These three requirements in themselves are not sufficient. Before the requirements are done being written, for example, there will need to be a definition of what “operate nominally” means. Similarly, the “at least three years” requirement is not enough by itself: three years would be difficult or impossible to meet if the intended environment were the surface of Venus; it would be almost trivially easy in the intended environment were an air conditioned clean room. Adding more information about the environment is necessary to interpret the three-year condition—for example, what is the expected radiation environment at those altitudes?

The three example requirements are not sufficient in another way: they are high-level and provide the designer of, say, a battery subsystem no guidance about how the battery must be designed so that the spacecraft meets these requirements. The derivation or flow down is the topic of an upcoming section.

34.2.2 Rationale

A well-written requirement is concise. As such, it makes a statement about what a component should do—but the text of the requirement does not capture why the component should do that.

Good requirements should include a rationale statement that documents the thinking that went into choosing to make the requirement. The rationale does not change the requirement; it only adds explanation. The rationale helps those who must come along later, after the requirements are written, to understand or evaluate the requirements. It helps educate other engineers about considerations that may not be obvious. It helps those who later need to revise requirements understand what constraints there may be on the requirement they are changing.

34.3 Multiple requirements

Requirements actually come in groups; they are practically never singular.

The meaning of a group of requirements is the logical and of all of them. If there are ten requirements, an implementation complies with the requirements if it complies with all ten of them individually.

There are two issues to watch out for when there are multiple requirements: contradictions and exclusivity.

34.4 Organizing requirements

Even a moderately-sized system will typically have thousands of requirements. Users need some kind of organization of all those requirements in order to find the requirements they will be working with.

There are three concepts to discuss: organizing by subject, organizing by sections, and hierarchical writing.

34.4.1 Levels of requirements

People use requirements for different purposes. This leads to fundamentally different kinds or requirements.

At the most abstract level, the general product or mission objectives capture what stakeholders want the system to do—its purpose. These almost always start as general, vague statements. The stakeholders, system engineers, and product managers refine these over time into a clearer definition of the system’s purpose. The exercise may or may not result in proper requirements statements, but it is worth treating the results as if they are requirements and showing how the top-level system requirements derive from these objectives.

Projects also have guiding objectives that do not specify the system directly, but instead define policy or standards that the system must adhere to. There are many kinds of policies, including:

• Business policy: common rules for how the organization operates; expected profitability margins; expected customer base
• Security policy: what kinds of hazards, threats, and attacks should be addressed in the system design; what should be protected; rules for prioritizing different attacks
• Safety policy: what entities should be considered for safety; what hazards to consider; acceptable incident rates for different hazards; can include things like launch assurance standards
• Regulatory policy: regulations and laws that the system must comply with
• Development standards: standards that govern how the team designing and building the system should go about their work, including quality standards such as ISO 9001 or process standards such as NASA NPR 7150.2
• Other standards: industry or government standards that will inform the design of the system, such as standards for hardware components or for human-machine interface design

It is helpful to organize the product/mission objectives and all the various policies and standards into separate collections, identified by the kind of policy or source of objectives. For example, one can maintain one collection for business policy and a separate one for the quality assurance standard being used to build a system.

The top-level requirements on the system as a whole are part of the formal or semi-formal definition of what the system is to do. These requirements say what the system is and does when looked at from the outside, as a black box. These requirements are best kept separate from the more vague product/mission objectives—the objectives represent desires, while the top-level requirements represent the commitments made for what the system will do. The derivation mapping from objectives to top-level requirements provides a place to record the rationale for why different decisions were made about the commitments in the system, and why the decision was made not to commit to supporting some desires, represented in objectives.

Requirements on lower-level components provide definitions of what the pieces that make up the system must do. These obviously have a different scope than the top-level requirements for the whole system.

34.4.2 Organizing by subject

The first concept is that requirements should be organized by their subject, following the component breakdown structure.

The system objectives are those requirements that apply to the system as a whole. These typically encode the CONOPS for the system, along with requirements derived from the process or design standards.

The rest of the requirements apply to specific components within the system. The component breakdown structure defines what the components are, and gives them names.

Organizing by component is important for proper verification, so that each requirement can be connected to the implementation artifacts that are expected to comply with the requirement, and so that the implementer of some component can properly determine all the requirements they need to adhere to.

34.4.3 Organizing by section

One single component or process/design standard can often have several hundred requirements. Users can find and work with all these requirements more easily if they are organized by topic as well as by subject.

This can be done by creating a set of topic sections within each component. Often these sections are the same for all components—sometimes empty when they are not relevant, but having the same organization across all components help people find what they are looking for.

There is no one recommended set of sections that will apply to every system. The choice of sections is affected by the kind of system or components being developed, as well as by process and design standards. For example, if an automotive project is following the ISO 26262 Functional Safety standards [ISO26262], the Safety Goals and/or Safety Requirements should be collected into one section.

As a starting point, we have used variations on the following set of sections in several projects:

• Operational requirements. These relate to how the component turns on and off, and the major operational modes of the component.
• Functional requirements. These record the behaviors or functions that the component is expected to provide (when it is turned on, if that applies)
• Service or life cycle requirements. These address how the component is to be manufactured, installed, maintained, and retired
• Budget limitations. This includes data rates, mass, power consumption, RF emitted or received, heat emitted, or gas/vapor emissions
• Environment. What the component must be or do in its environment. For example, vibration resistance, gas or dust resistance.
• Discipline-specific sections. This includes sections for safety, security, and regulatory compliance.
• A miscellaneous section for requirements that don’t fit into other categories.

It’s a good idea to work out one or a few section structures that work for your project, then use those sections consistently across all components.

Keep in mind that some requirements will always fit into multiple sections. For example, a requirement may both be about regulatory compliance and define a function the component is supposed to provide. Try to make consistent choices about which section a requirement goes in, but don’t try to make some perfect hierarchical section scheme that would let people avoid making such choices.

34.4.4 Hierarchical versus flat requirements

There are two general structures for organizing requirements on a particular topic:

• As a single-level or flat collection of requirements, all at the same level
• In a hierarchical or outline structure There are pros and cons of each approach. The choice of which you follow will depend on the style of working in your project, the capabilities of the tools you use, and the process requirements that apply to your organization.

The flat organization has all requirements within a section be at the same level. Each requirement is independent of the others and can be understood only by reading the text of the requirement.

The hierarchical organization places requirements into an outline, with general requirements and more specific sub-requirements. The sub-requirements must be read and understood in the context of their parent. The sub-requirements provide details, clarification, or limitations on the general parent.

Consider a set of requirements for security on a TCP/IP communication channel. The general requirement is that the communication channel should be authenticated and encrypted. In outline form, this looks like:

1. Communication channel X must implement security mechanisms
   1. Communication channel X must require authentication before application data is exchanged
      1. The authentication protocol must mutually authenticate both parties to each other
      2. The identity being authenticated must be granted by the organization’s security management system
      3. The authentication protocol must be resistant to man-in-the-middle attacks
      4. The authentication protocol must support revocation of either party’s credentials within X minutes
   2. Communication channel X must maintain integrity and confidentiality of the application data being exchanged
      1. The confidentiality protection must be resistant to traffic analysis

Consider requirement 1.1.1, requiring mutual authentication for the communication channel in question. The requirement for mutual authentication must be understood only to apply to communication channel X. There could well be another communication channel, called Y, that does not have the same authentication requirements.

Written in a flat style, the requirements might be expressed as:

1. Communication channel X must require authentication before application data is exchanged
2. The authentication protocol used for communication channel X must mutually authenticate both parties to each other
3. The authentication protocol used for communication channel X must use identities granted by the organization’s security management system
4. The authentication protocol used for communication channel X must be resistant to man-in-the-middle attacks
5. The authentication protocol used for communication channel X must support revocation of either party’s credentials within X minutes
6. The communication protocol used for communication channel X must maintain confidentiality and integrity of the application data being exchanged
7. The communication protocol used for communication channel X must provide confidentiality protection that is resistant to traffic analysis

Each of these statements can be read on their own; each statement includes all the necessary qualifications (“the protocol for communication channel X must…”) to identify the scope of its subject without having to refer to other statements.

There are pros and cons of each approach.

• (Pro) Flat organization allows each requirement statement to be read and understood on its own, without reference to other requirements
• (Con) Flat organization requires some requirement statements to include a lot of redundant text to identify the scope of the subject. The redundancy makes it more tedious to write the statements, and leads to errors where one of the qualifying clauses in the subject doesn’t get edited and becomes inconsistent with the others
• (Pro) Hierarchical organization makes it easier for the reader to scan for a particular requirement, and makes the individual statements easier to understand
• (Con) Hierarchical organization means that sub-requirements do not stand alone, but must be read in the context of their parent.

34.4.5 Requirement identifiers

Every requirement needs a unique identifier.

People use this identifier to refer to the requirement, including using it as a bookmark or link to reference the requirement in other documents. Software check ins to a repository often use the requirement identifier to indicate what functionality is being added to the repository. Task management systems use requirement identifiers to track the progress on implementing and verifying particular requirements. In general, the requirement identifier enables the integration of requirements management with other tools and tasks

The identifier must be stable. That is, once a requirement has been given an identifier, that identifier should not change. The text of the requirement can (and will) change, but the identifier remains a stable way to refer to the requirement in documents, email, and other messages without having to track down all the uses of the identifier and change them.

It is good practice for the identifier to convey some information about the requirement. At minimum, the identifier should make it clear what component or body of external requirements the identifier applies to. If one writes requirements hierarchically, then using the number of the requirement in the outline is a good identifier.

Having the identifier carry some information helps the user check that they are referencing the requirement they intended to reference. It also helps the reader to know generally what the writer is talking about, without going into a requirements management system to check.

For many projects, I have used the format <component id>:<hierarchical requirement number> as the identifier. For example, space.eps.panels:3.4.2 for a requirement applying to a spacecraft’s solar panels.

There are requirements management systems that use a universal, flat namespace for identifiers, such as REQ-82763. This is not a good identifier, because it makes it hard to check when one has accidentally mistyped or miscopied the identifier into another document. If one accidentally types REQ-82764 into another document, that other requirement could apply to a completely different component—and the mistake is obscured.

34.5 Writing good requirements

Requirements are a way of communicating between people on a project: between the customer and systems engineers, between those who look at how multiple systems work together and those who implement the pieces, between those who design and those who test. A good requirement is one understood equally well by all the people who use that requirement.

Writing good requirements takes practice, but the following guidelines will help in writing and reading requirements.

34.5.1 General form

Individual requirements have a general form:

The subject is often a component named in the component breakdown structure. It should be named explicitly:

The majority of requirements use either the word “shall” or “must”, depending on the organization and industry. “Shall” indicates an assertion that the statement about the subject is to be true in the implemented system. “Must” expresses the obligation that the statement will be true in the system. In practice the two words mean the same thing when writing requirements.

The property is a predicate that should be verifiably true about the subject.

Writing the predicate is usually the complex part of writing a requirement. In some cases the predicate is simple:

In other cases, the predicate must have conditions added, saying when or under what conditions the predicate applies:

Sometimes the requirement statement is easier to read if the condition clauses are presented in a different, natural order. However, the semantics remain the same: the clause is part of the property statement:

34.5.2 Single topic

A requirement should specify a single property of the subject. The examples above all deal with a single property.

There are requirements that may have multiple things in their property statement that still deal only with a single property. For example:

Formally, this requirement deals with a single property: what color the widget may be painted. The color is restricted to a set of three colors—but the property in question is the color.

Note that this requirement is slightly ambiguous: it is not clear whether the widget can be painted only one of those colors, or some mixture of them. This requirement could be improved by either rewriting it as:

Or adding a second requirement:

34.5.3 Clarity about subject

A good requirement must be clear about what thing it applies to. In general it is best to write down a proper name of the subject—the name of the relevant component in the breakdown structure, for example.

This rule makes for a lot of repetition in requirements. “The control system must X”, “The control system must Y”, “The control system must Z”, and so on. While it means a little more typing, using the component’s name in each requirement means that each requirement can be understood on its own.

34.5.4 Consistent language

Use consistent terms throughout requirements. Always call component X by one name; don’t change it from requirement to requirement. Always call some one function by the same name, so that it’s clear that all the relevant requirements really are talking about the same thing.

Having lists of names or terms helps those who write requirements to use consistent terms, and provides those who read requirements with definitions when they need to confirm what a term refers to. This means:

• Define the component breakdown structure, and use the component names in that structure when writing requirements
• Provide a list that defines the functions that a component must provide. Use the function names consistently when writing requirements, and provide a definition of the function that will help a requirement reader understand the requirement statement
• Provide a glossary of terms with technical meanings. Use terms consistently with the glossary, and include definitions of terms that are clear enough to explain the terms to readers

34.5.5 Plain language

Requirements (and the rest of specifications) may be written by one or a few people, but they will be read by many people. The readers need to understand correctly what the requirements mean. Many of those readers will be learning about the system by reading requirements or other documents, so they won’t enter into reading the requirements with the same context that system engineers writing the requirements will have.

This means: don’t get fancy with requirements language. There are some ways that requirements will sound stilted, like the subject-mode-property form. There is some technical jargon that is needed to make the requirement precise. But don’t make the language more complex than it needs to be.

For any words or phrases that do not have a meaning that will be obvious to all your readers, help them out by defining how those words are being used in the specifications. Start with “must” versus “shall” and any other mode words (see Advanced Requirements below). Provide a glossary of the definitions of the rest of the words.

34.5.6 Negative requirements and “only”

Many organizations prohibit requirements that say “shall not”. Negative requirements have their place, but they are tricky to get right. The problems arise with exactly how broad or narrow the requirement actually is.

Consider a component implementation that could do one of three behaviors, A, B, or C.

If the component has a requirement “the component shall do A”, the implementation satisfies the requirement (it does A). That is because the requirement, as written, allows for the implementation to do other behaviors as well.

If the component has a requirement “the component shall only do A”, then the implementation does not satisfy the requirement because the implementation might do other things.

Now consider a requirement such as “the component shall not do D”. The implementation does satisfy the requirement, but not necessarily in a helpful way. Just because the component doesn’t do D, what should it do? Are behaviors A, B, and C all acceptable? What about behavior E?

In most cases it is clearer to name exactly the behaviors that are required, because that is unambiguous. One can write verification conditions to test exactly what is allowed.

Sometimes, however, one should write a negative requirement. If there is some behavior that really, truly must never happen, then writing a “shall not” requirement calls out that important condition, and a verification test can be designed to show that the system will not do the thing it isn’t supposed to. The negative requirement should usually be paired with a positive requirement that says what the system should do instead.

Safety and security properties often require stating a negative requirement, because these properties are fundamentally definitions of things that the system is to be designed not to do. I have not been able to imagine a way to write “a robot may not injure a human being” [Asimov50] as a positive requirement.

Verifying negative requirements is more complex than verifying positive requirements. See Section 14.4.

34.5.7 Avoid “it”

Avoid the word “it” and other non-specific pronouns or modifiers (“they”, “those”, “them”, “its”). Repeat the name of a thing involved in the property, even if that seems repetitive and wordy. An example:

This is better written:

Because the “it” in the first example is ambiguous: the word could refer to the mode or to the control system.

34.5.8 Avoid impossibly high bars

There are things that we want a system to do. When writing a requirement, it is tempting to write something like

Unfortunately, this three-year required property of the spacecraft is virtually impossible to meet (unless, maybe, the “spacecraft” is a large, inert chunk of rock). A spacecraft has many parts, operates in a difficult environment, and is built by fallible humans.

The problem with this requirement is that it sets a bar that is so high that no real spacecraft can meet it. The requirement does not allow for any off-nominal operation. It doesn’t allow for a spacecraft to have a temporary fault and then recover. It doesn’t allow for debris to impact the spacecraft. In fact, this requirement is met only when the spacecraft is perfect for those three years. Any real spacecraft will fail verification if it has a requirement like this.

This kind of requirement needs to be modified to something more realistic. There are many ways to do that. The NASA Systems Engineering Handbook has the rule that a requirement should specify “tolerances for qualitative/performance values (e.g., less than, greater than or equal to, plus or minus, 3 sigma root sum squares)” [NASA16, Appendix C].

Three common ways are:

• To place a probability on the requirement: function nominally with probability at least 95% for three years while on orbit
• Provide an availability or reliability measure on the requirement: function nominally at least 99.3% of the time for three years on orbit
• Provide a definition of “nominally”, either in other design documents or in additional requirements, that allows for the spacecraft occasionally to go into safe mode or otherwise be temporarily out of service

Of course, these are often combined.

34.5.9 Measurable conditions

The point of a requirement is that someone can determine whether an implementation complies with the statement in the requirement. Operationally, this means that a requirement can be verified (see the section on verification below).

One way to make a requirement measurable is to specify the condition quantitatively. For example, a spacecraft’s battery must be able to store at minimum X milliamp-hours. It’s not hard for a test engineer to see how to create a test to verify that the battery complies.

Other requirements, especially those that specify an action that should be taken under some condition, aren’t quantitative, but instead are measured by observing whether the required action is taken. The verification tests will involve either creating the condition under which the action is to occur or observing that the condition has occurred, and then observing that the required action has been taken. For this kind of requirement to be useful, a test engineer must be able to understand accurately the enabling condition and be able to create or detect that condition. The test engineer must also be able to understand the action that is supposed to occur, and detect that it has occurred. If the enabling condition or action can’t be detected, then the requirement is not readily measurable.

Requirements on low-level components are often easier to make measurable than requirements on high-level components. This is why high-level requirements are often verified by looking at requirements derived from the high-level requirement rather than by trying to construct a verification test directly on the high-level requirement.

34.5.10 Unverifiable conditions

When writing requirements for human-machine interaction or user interfaces, the underlying need is that a user can understand what the system is doing, and give it the right commands so that the system does what the user wants.

How would someone verify that the system as designed or implemented actually meets this objective? The statement is too vague actually to test.

There are multiple ways to address this issue.

First, one needs to break the objective up into a number of more-specific objectives. This often involves putting together a list of what it means to “understand what the system is doing”. This might involve:

• Perceiving what operating mode the system is in
• Observing fault conditions that will change operating behavior
• Observing how much fuel or electrical charge the system has remaining
• Interpreting the indications to understand the state of the system

And so on.

This breakdown is an improvement over the original desired objective, but the conditions are still not verifiable. As we will see in the later section on requirement derivation, these can be turned into high-level requirements that are broken down further, and the verification condition on these high-level requirements consists of, first, verifying all of the derived requirements, and then showing an argument that satisfying all the derived requirements shows that the high-level requirement is satisfied.

The derived requirements about “perceiving” or “observing” are themselves not verifiable: how does one verify that a person has observed, or can observe, some state of the system? This needs to be broken down into yet further, more specific requirements. For example,

Is a process, consisting of a chain:

If all these steps are satisfied and work correctly, then the person should be able to see the amount of fuel remaining.

Focus on the last two functions in the chain: that a person can see the indicator and that they can observe the indication. Seeing the indicator can be in turn broken down into further requirements, primarily on the physical structure around the person. For example, some of these might be:

• The person observing must have an unobstructed line of sight to the indicator
• The indicator must be visible in all the lighting conditions that the person will experience
• The indicator must cover a large enough portion of the person’s field of view that they can see the details of what the indicator is showing

There is some prerequisite information needed to verify these examples. For example, what range of sizes will the users be? In order to check for unobstructed line of sight, one must know where the user’s head will be. What visual acuity or color perception abilities are required of the users? A color blind user will not be able to perceive some color differences that might be used to convey necessary information. What expectations will a user bring to the task? If a user is socially conditioned that green means good and red means bad or stop, using different colors to indicate good or stop will be hard for a user to interpret.

How would one go about verifying these requirements? There are multiple techniques that will help—and usually the techniques must be used together to really check whether a requirement is satisfied. These techniques are a combination of analysis using models and real-world measurement.

• Analysis of CAD models or physical models of the environment. If we know where the indicator will be placed, what else is around it, and where the user’s head can be, one can determine if something will obstruct the line of sight. Similarly, building a model of all of the anticipated lighting conditions can allow one to find the lighting situations that are likely to be difficult for perception, such as having the sun in a user’s eyes when they try to look at the indicator, or full darkness.
• Standards. There are many standards for color, contrast, visual size of an indicator, and many other aspects of user interface components. Meeting a standard may be sufficient for determining whether the requirement is met.
• Experimentation. Build a mockup of the environment where the indicator and user will be, put users in that mockup, and measure how well they do at perception tasks.

The experimental approaches are often the most expensive in time and money, but they are the gold standard for verifying a human interface requirement. Conforming to standards can help address expectations that users will bring to tasks.

In summary, there are several tools for addressing requirements that are too vague or complex to verify:

• Writing a high-level requirement, breaking it down into multiple derived requirements, and showing that satisfying those derived requirements means that the high-level requirement is satisfied
• Consider the chain of functions that leads from the basic states of the system or component to the desired outcomes, and use those functions to guide a breakdown into lower-level requirements
• Determine how to perform verification on the lowest-level requirements, using a combination of analysis, standards, and experimentation

XXX revisit this section to bring it into line with the Leveson viewpoint on user interaction as control

34.5.11 Detail appropriate to the level

Requirements should be written as a description of what one sees in a component when looking at it from the outside—a black box view. A good requirement does not go into how the feature or behavior is implemented inside the black box.

Put another way, the requirements for a component are documentation of how the component fits into the system around it. If component A is part of a larger component B, the requirements on A document what the implementation of B needs for A to do its part correctly. If components C and D are peers, the requirements document what they will need from each other for both to do their job.

This matter connects directly to requirements derivation from component to subcomponent, which is discussed in the next section.

There are four reasons to follow this rule.

1. Requirements aren’t the only specification of the system. There are design documents whose job is to document how a component will be implemented internally.
2. Many requirements are written before a component’s internal implementation is understood. The requirements serve as a record that the component designer can come back to to make sure they have designed or built a component that meets the needs of the components or users that will interact with the component.
3. Things change. Components get redesigned. If a component’s features don’t change but its implementation does, the requirements defining the component shouldn’t change.
4. Saying what a component is supposed to do leaves room to document the thinking or the rationale that led from the external what to the internal design of how the component provides the whats. This helps others who come along much later to understand the system—in particular, it helps when a requirement needs to change and a new person has to work out what effects that change in requirement will have on an implementation.

It is tempting to skip right to the details of how a component is built. Don’t do it; provide other people the benefit of your understanding of the problem, not just the final design answer.

34.6 Requirement derivation

XXX revisit this to bring it in line with system model terms

No requirement stands entirely on its own. Almost all requirements have some reason that they have been included in a system, starting with: this requirement is necessary so that the system meets some objective. In lower-level components, the reason often is: this requirement is necessary so that this component provides some feature that other components depend on.

These are examples of requirement derivation. Derivation encodes the relationship between requirements.

Almost all requirements are derived from other requirements, and the requirements in a system must keep track of how one requirement leads to another, or how one is dependent upon another.

There are several kinds of relationships that people record. Some of these are:

• A lower-level component has a function that a higher-level component will use
• One requirement within a component implies other requirements on that same component
• A component passes on a general requirement to its subcomponents
• Two peer components will be interacting, and depend on each other’s functions

Let’s look at each of these kinds of derivation.

34.6.1 Subcomponents providing features for parent

A parent component has a requirement that the component provide some feature. The requirement in the parent specifies what the parent must do, but does not specify how to implement that feature. The design of the parent component, and later, the implementation, document how the parent component will satisfy that requirement.

When the designer decides on the implementation, they will decide (among other things) how the parent component will use subcomponents to implement the feature. These decisions create requirements on the subcomponents so that they provide the features that the parent component will use.

The reason for these requirements on subcomponents is that they are necessary to satisfy the requirement on the parent component. A derivation relationship between the parent requirement and the subcomponent requirements documents why the subcomponents have the requirements they do.

Consider a spacecraft example. The spacecraft as a whole has a requirement that it be able to point at a ground location, with some number of degrees of accuracy. To implement that feature, the spacecraft designer chooses to use the spacecraft’s attitude control system to point the spacecraft toward a ground location, and then slowly rotate the spacecraft as it passes over the ground location. The parent component—the spacecraft—has the high-level requirements for what it needs to do. The subcomponent—the attitude control system—must be able to slew accurately to an initial pointing vector, and then be able to slew slowly and accurately until the spacecraft is done with an observation. The slewing accuracy and speed are the derived requirements on the attitude control system.

The process continues recursively. The attitude control system designer decides to use reaction wheels as the primary attitude control mechanism. The requirements for slewing accuracy and speed create requirements on the reaction wheels for how quickly or slowly they can turn the spacecraft.

34.6.2 Internal derivation

Some components will have a requirement that specifies a very high-level capability the component must provide. For example, in a section on disposing of a component that is being discarded:

There are several ways this requirement could be met: destroying the retired component in house, crashing the component into the atmosphere or ground in a way that will assure the component is destroyed, or erasing the data on the component before giving the component to an outside entity for recycling.

Whatever the implementation decision is, it creates more requirements on the component, and those requirements derive from the decision on how to satisfy the requirement on protecting confidential information. If, for example, the implementation decision is to recycle a retired part, then this might lead to requirements like:

In some organizations, the practice is only to record derivation from one component to another. Sometimes that works out; in the example, the requirement for an erasure command could be on a command handling subcomponent, and the erasure requirement could be on a memory component. However, some components do not break down into subcomponents easily—for example, when the component is being implemented by an outside vendor. In other cases, it is simply clearer to document the implementation requirements for the component directly and then passing the requirements through to subcomponents, so that a user can see the totality of the functional interface to the component in one place rather than having to search through subcomponents for something they don’t know exists.

34.6.3 Pass through

External objectives and standards often impose general requirements on “all components of type X”, or the like. For example, an automobile might have a requirement that all electronic components function nominally across a temperature range of -40º C to +125º C. (See the section on Sets as subjects below for more on this.)

This requirement can be placed on the automobile as a whole; the requirement might read

If the automobile includes engine, braking system, and entertainment systems as parts, the temperature range requirement can be passed down to those subcomponents:

But the entertainment system, which is not safety critical and operates in the more benign environment of the passenger cabin, might have the requirement:

In these examples, the general requirement is copied down into lower-level subcomponents until it reaches some component (such as the braking controller in the example) that does not have further subcomponents. Sometimes the requirement is copied verbatim, just changing the scope of the subject; other times, some component will have a variant on the general requirement.

This kind of derivation is sometimes referred to as allocating requirements to subcomponents.

34.6.4 Mutual dependency

Sometimes two components are peers of each other, and need to interact. A fuel tank provides fuel to an engine; a spacecraft communicates with a ground station to send telemetry and receive commands; client and server applications send messages to each other.

These interactions involve requirements on each of the components involved, showing how the components support each other. The fuel tank must send fuel; the engine must consume fuel. The spacecraft must be able to communicate with the ground station; the ground station must be able to communicate with the spacecraft.

This leads to pairs of requirements that record this mutual dependency. At a high level,

and

These two requirements should show a two-way relationship with each other. (Formally, this introduces a cycle in the derivation graph.)

34.6.5 Using derivation

Derivation shows how requirements are related to each other.

Systems engineers use the record of these relationships for several tasks.

• Determining whether a design of the system can satisfy its top-level objectives, and encoding how a system’s design satisfies those top-level objectives.
• Determining whether a particular requirement is actually needed (and why).
• Tracking down the effects of making a change in one piece of a system on the rest of the system.

A derivation relationship between requirements on two different components helps to document the implementation approach for meeting a higher-level requirement. When a designer looks at the high-level requirement, they can see what features are used to implement the high-level requirement. The lower level requirements and their rationale allow the designer to see the argument that the implementation will be sufficient to meet the high-level requirement. This makes the design rationale available to people who didn’t create the design in the first place, but need to understand it to evaluate it or to make changes.

The section on analyzing requirements, below, goes into more detail on how one can look at the requirement derivation relationships to evaluate completeness or sufficiency, to argue whether low-level features are actually necessary, and to trace out the effects of making a change in requirements.

34.6.6 Viewing derivation

There are two ways that a user should be able to see derivation relationships. First, when looking at any one requirement, the user should be able to see what requirements this one is derived from directly, and what requirements derive directly from this one.

Good requirement management tools will also provide a view of the graph that shows derivation graphically. Derivation relationships can be viewed as a graph, as a way to see multiple levels of derivation. The graph is typically mostly a tree or DAG, but there are legitimate reasons that the graph will sometimes have cycles (between peer components, for example).

Here is an example showing how a top-level requirement is the source for a number of other requirements.

34.7 Advanced requirements

All the requirements discussed so far are simple requirements. Simple requirements have a single, clearly specified subject component. Each simple requirement expresses one property about that subject that must be true.

Simple requirements are not sufficient to express every need that real systems encounter. There are two that we have seen many times: requirements on sets of components, and requirements for standards.

34.7.1 Sets as subjects

Consider a system where all code is expected to adhere to a published coding standard. The implied requirement does not apply to any single component; it applies to all of them that include software.

This expectation can be written as a top-level requirement on the system as a whole:

The subject of this requirement is the set of all software components in the system. The property is that their implementation adheres to the named coding standard.

This kind of requirement is placed on the top-level system, and then each first-level subcomponent includes a derived requirement that propagates the requirement downward:

On a component Y that has software as part of its implementation then has:

If component Y has subcomponents, Y should also have a second requirement that continues to pass the requirement down to Y’s subcomponents.

This is an example of a general technique:

• At some component, levy a requirement that is expected to apply to some subset of the subcomponents of that component
• Pass the requirement down from component to subcomponent by giving the subcomponent a derived requirement that is nearly a copy of the original, except for limiting the set of components
• When the derivation reaches a component to which the need applies, write a simplified requirement that names only that one component as its subject

34.7.2 Writing for standards

Many texts on requirements approach the subject from an assumption that there is one system being built: these are the requirements for System X. System X will be built in its entirety as specified; any and all requirements must be satisfied.

Writing standards is a different problem. A standard is specifying requirements on multiple hypothetical systems that may exist at some point. Those systems will not be identical, but the systems that adhere to the standards must adhere to the requirements in the standard.

Standards often provide options. The standard has a set of optional features. If the system chooses to implement those features, the features must conform to the standard. However, the system does not have to implement those features. This means that the system does not have to satisfy every requirement in the standard.

Some standards also present best practices. For some feature, it is recommended that the feature conforms to a part of the standard, but it is not absolutely required to do so.

The vocabulary of “shall” or “must” does not accommodate these situations well. The Internet Engineering Task Force (IETF) has defined a richer set of requirement modes. For example:

The words used to indicate these more complex conditions must be defined just as carefully as “must” or “shall”, and must be used consistently.

34.8 Analyzing requirements

Many people think of requirements only as a contract for guiding implementation and a checklist for performing verification tests later. However, requirements—along with other specifications—are useful in themselves for helping build a design and making sure the design is good.

There are three kinds of analysis that systems engineers do on the requirements themselves:

1. Ensuring that the requirements (and specification) are complete
2. Ensuring that the design is minimal, meaning that the design only contains features that it actually needs and nothing extraneous
3. Ensuring that the requirements are consistent
4. Understanding the effects of making a change to one part of a system design

These are all analyses that should be done on the specifications of a system, including the requirements, and not delayed until implementation. Some of these tasks are easier to perform on the abstracted and simplified view of the system that specifications give. Performing these tasks before implementation will reduce the amount of re-implementation needed when one finds that the requirements aren’t sufficient or minimal.

34.8.1 Complete design

The expectation is that if a system is built to conform to its specification, including requirements, that the system will do the job that its users need and do it correctly. (Of course, this assumes that the top-level specifications are themselves a correct and complete record of the users’ objectives; we discuss this more in the section on validating requirements below.)

To meet this expectation, the system’s requirements need to be complete and correct. This means that when one looks at any given top-level requirement, one can trace out the features on other components that will be used to implement the requirement and argue that those features will combine correctly to produce the desired result.

There are two parts to this analysis:

• At each level of derivation, are the derived requirements complete for their parent? Is there a rationale that shows how these derived requirements are necessary and sufficient to implement the parent?
• Are the leaf requirements concrete, implementable, and verifiable?

Having tools that allow one to view parts of the derivation graph in visual, graphical form is invaluable to performing this analysis.

Consider an example. A UAV (drone) is supposed to receive and process commands from an operator on the ground. This leads to requirements:

These requirements are not complete, because they leave out a critical step: when a command is sent from the ground operator to the UAV, the message first goes to the transceiver. The receiver extracts the message, and then sends the message to the command and data handling component. The example omits the part about the transceiver and command handler passing information to each other. This means that one could build an aircraft that had a radio and had a flight computer, but the two would never talk to each other. Obviously, the UAV would not be acting on commands with that design.

This leads to a more complete set of requirements:

In the example, the communication between the transceiver and command handling components should be documented in some other specification for the UAV, perhaps an activity diagram showing how commands flow through components. The requirements then need to be checked against these other parts of the specification to make sure that all of the functions in each of the steps are reflected in the functions each component is required to implement.

Sometimes determining whether a set of requirements is complete or not will require further analyses. As a simple example, the maximum mass for an aircraft might be X kg. Making sure that the aircraft’s overall mass comes in under that limit means enumerating all the components in the aircraft that have mass, adding up their mass, and determining that the result is below X kg. For that analysis to be complete, it cannot leave out, say, the mass of the motors; all components must be considered.

As a more complex example, a system might have a maximum acceptable failure rate target. Being able to argue that the system is reliable enough involves performing a fault tree analysis, enumerating all the ways that failures in components can lead to system failures. The analysis cannot leave out components and be complete; nor can it leave out some failure modes of some of those components.

Checking whether the design is complete is not a simple task that can be performed just by inspecting the graph of requirements. The analysis is helped by being able to see the requirements, but it requires imagination and effort to actually check the result.

XXX Sidebar: relationship to Goal Structuring Notation and safety cases

34.8.2 Minimal design

Every feature and every requirement on a component should have a reason for being there.

At the top level, for the system as a whole, only features that address customer needs or business objectives should be included. At lower levels, the only requirements that should be placed on components should be ones that are actually needed to make the system work properly—meaning the system meets those top-level objectives.

34.8.2.1 Tracking the purpose for every requirement

The derivation relationships between requirements encode the reasons for a requirement to exist. This leads to a condition that should hold across all requirements:

This is straightforward to check using the derivation graph: every requirement should derive from at least one parent requirement, and it should be possible to trace upward through the derivations to reach a customer or business objective.

Often while requirements are being developed, a requirement will be placed on some component without setting up the derivation. This requirement will not have a parent, and so the checking method will flag it. But what to do then?

In most cases, there was a good reason that someone wrote that component requirement. When one finds a requirement that is not documented as supporting some higher-level reason, it is worth exploring why that requirement is valuable. In some cases, the parent requirement(s) are present, and the requirement just needs to be linked to them. In other cases, the requirement can be a clue that there is some higher-level principle that the writer had in mind, and that higher-level principle should be added into the requirements higher up in the system.

For example, consider a data storage component where an engineer placed a requirement that all data be stored in an encrypted form. As written, that requirement doesn’t derive from any other requirement. But why did the engineer believe that encryption was necessary?

One answer is that encryption isn’t necessary. In that case the encryption requirement can be removed. Another answer is that the engineer wrote that requirement because they believed that the component would be storing confidential data that should be protected against disclosure. In that case, it is worth checking: does the system have requirements—or business objectives—about protecting confidential data? If not, then this exercise will have found a topic that has not been adequately addressed, and new requirements need to be added to make a correct specification. Those requirements should be added throughout the system, and the requirement we started with should show that it derives from those new features.

Many such requirements result from external standards that are supposed to be met, such as regulatory, safety, or security standards. Those standards should be included in the external objectives for the system, their requirements should flow down through the system to the components where the standards apply. This produces a record of how the system’s design complies with those standards.

34.8.2.2 Finding unnecessary requirements

Some requirements that show how they are derived from some parent requirement are still not actually necessary.

There is no simple, mechanical way to find these unnecessary requirements. However, the analysis used to determine whether a collection of requirements is complete is also useful for finding these unneeded requirements.

Consider this example:

The requirement about encryption is not actually needed for the system in question. That is because the connection between the transceiver and command handling components is physically contained within the UAV, and the physical encapsulation provides enough security to protect the messages passing between the two. The encryption requirement can be removed with no loss of capability.

However, in this example, the engineer who wrote the encryption requirement had a good idea but expressed it wrongly. The engineer understood that the integrity of communication between the two components was important; a command that was properly received but garbled in being sent to the command handling component could be a problem. The presence of the encryption requirement should be replaced by a less costly requirement, that the channel must protect the messages it carries against corruption.

34.8.3 Consistency

Consistency in a body of requirements is when the requirements don’t contradict each other. If requirements do contradict each other, the system as specified isn’t implementable and the specification needs to be fixed.

Broadly speaking, there are three kinds of consistency that one should check:

1. Consistency among requirements for one component
2. Consistency between requirements on either side of an interface between two or more components
3. Consistency between requirements on a higher-level component and the requirements on subcomponents that should show how the higher-level requirements will be implemented

As long as requirements are written as text, and not in a formal notation, consistency checking will be manual. It involves reading through each requirement, finding other requirements that address related topics, and checking that they are consistent with each other.

Some inconsistencies are fairly easy to detect. If one requirement says component X shall be blue and another says component X shall be red, it’s obvious—one must just read through all the requirements on component X and see that two requirements both deal with the color property and they say opposing things.

Other inconsistencies are harder to spot because they do not use the same language in the properties they are specifying. As an example, one requirement might say component X shall use encryption algorithm Y while another requirement says component X shall use protocol standard Z. If protocol standard Z allows encryption algorithm Y, this is fine. But if the standard does not allow that particular encryption algorithm (perhaps because the algorithm is outdated and no longer considered secure enough) then there is an inconsistency.

Another class of inconsistency comes from the states a component can take on. Elsewhere in the specification of a component, there should be a definition of the state machine that the component is supposed to follow. The requirements translate that state machine into individual actions that the component is expected to take in response to particular inputs. It is easy—especially when editing or updating the component’s specification—to have two requirements: when condition A occurs, component X must transition to state Y and when condition A occurs, component X must transition to state Z. The inconsistency can be more subtle, such as leaving out some transition, or using inconsistent definitions of the condition that causes the transition. This class of problem can be addressed by having a single, clear definition of the state machine the component is expected to follow, and then checking the requirements against the state machine.

Finally, another class of inconsistency that can be hard to detect has to do with timing. Two requirements can impose timing constraints that cannot both be satisfied. For example:

There is no way for component X to meet the timing requirements given the order that events must occur. Building a timing model of the component in question, and performing a timing feasibility analysis using that model, can help find this kind of inconsistency.

This is by no means an exhaustive list of the kinds of inconsistency one must look for.

34.8.4 Effects of changes

Systems change. This can happen because customer needs change, or because technology changes, or because someone has found a better design for part of the system. A good development process supports constant evolution and change of the design and implementation of a system.

Not every change that is proposed will be performed. When someone proposes a change, someone else will analyze the proposal to determine the effects of the change. Based on this analysis, people may decide to go ahead, postpone the change, or not make the change.

The analysis must accurately determine:

• What components are affected by the change? Is it just one component, or do effects ripple through much of the system?
• What things will need to change as a result? Component designs, specifications, safety analyses, regulatory filings?
• How extensive or expensive will those changes be?

This analysis makes use of all the specifications in the system, but requirements are a major contributor. In particular, the derivation relationships help show how component features depend on each other, and thus help guide an analysis of how far some change will spread.

34.8.4.1 Effects of top-level changes

Top-level changes include adding a new feature to the system, removing a desired feature, or changing a standard or other external source of requirements.

If the change changes a top-level requirement, look at the derived requirements from that changed requirement and see if the derived requirements are still necessary and sufficient to satisfy the newly-changed requirement. If they are, then no further action is needed. If they are not, then the derived requirements must be revised, possibly adding or removing some of them. The process then needs to repeat with these changed derived requirements. If the change affects a requirement that supports a different top-level requirement, then one must check that the other top-level requirement is still satisfied by the changed derived requirements.

If the change adds a new top-level requirement, work out what derived requirements are necessary and sufficient to satisfy the new requirement. Look for lower-level requirements that already exist that can also support the new requirement. This may involve a change in design, not just requirements; this will cause more changes to propagate out.

If the change removes a top-level requirement, see if any lower-level derived requirements are no longer needed or can be relaxed. If so, work downwards to propagate the effects of those changes.

34.8.4.2 Effects of lower-level changes

Many more changes will come to lower-level components in the system. There are many reasons this can happen: because people have found that a design in process is infeasible or too costly; because a vendor’s part specification or availability has changed; or because someone has found a better design for some lower-level component.

Evaluating a lower-level change involves all the checks for a top-level change above, along with the need to see how the change will affect higher-level requirements. Will the change leave the higher-level requirement unsatisfied? Will this change make some other sibling requirement redundant (that is, the parent is satisfied without the sibling)?

Tracking down these effects is much easier if the derivation relationships among requirements are accurate.

34.8.4.3 Tools

Good tools help the process of evaluating changes. There are three features in particular to look for:

1. The ability to create an independent working version of the requirements, in order to try out changes before committing them to a baseline. The ability to see what has changed between the baseline and the working version and selectively merge changes into the baseline allow reviewers to understand the whole effects of the change and to accurately accept the changes.
2. A feature to mark some requirements as potentially changing and others as needing evaluation. This feature helps ensure that the change evaluation does not miss some important change.
3. The ability to record a rationale for a derivation relationship between requirements helps the people evaluating changes determine why a set of derived requirements was considered necessary and sufficient.

34.9 Validating requirements

XXX rewrite this to bring into line with introductory language on deriving verification

Validation is the process of determining whether a set of requirements accurately reflects the needs of the system. This can mean that the system will meet customer needs, or mission needs, or other external objectives.

It is important to keep validation separate from verification, which is discussed below. Validation is about seeing if the requirements (and the rest of the specification) is an accurate reflection of external needs. Verification is about seeing if the implementation is an accurate reflection of requirements. (Some software engineering texts focus validation on consistency, completeness, and similar properties. Systems engineering has generally kept those kinds of checks separate from validating customer or mission satisfaction.)

The validation process starts with checking the system objectives, business objectives, security and safety objectives, and regulatory objectives to see if they are an accurate reflection of the customer or mission needs. Presumably appropriate care has been taken while these objectives are being gathered and written down, but mission understandings or desires change over time and an independent check on the objectives will help avoid having problems be discovered late, when it is expensive to make changes.

At the top level, one should check:

• Is there anything in the top level that does not come from what the stakeholders want?
• Is there anything the stakeholders want that is missing?
• Are all the regulatory needs addressed?

At lower levels, one is checking whether the derived requirements from a parent are necessary and sufficient. The analyses for complete and minimal design, discussed above, cover those checks.

There are many different ways to validate a system’s specifications. They generally fall into two groups: analysis and simulation.

XXX improve language: analysis as formal method vs review as informal

Validation by analysis involves people reviewing the requirements and using their judgment to check the specifications. This can involve performing joint reviews with stakeholders so that they can check the requirements.

Validation by simulation involves stakeholders somehow seeing a model of the system in action. There are many ways to do this. Stakeholders can be invited to define some scenarios that represent how they will use the system, and then try out those scenarios using a model of the system. Some ways we have done this include:

• A desk or whiteboard exercise, where one or more engineers act out the system’s behavior and some stakeholders talk through what they would want to happen.
• Building a simple simulation model of parts of the system and letting the stakeholders try out their scenarios with the simulation.
• Building prototypes of parts of the system and having the stakeholders try out the parts of their scenarios using the prototype. This can be combined with a desk exercise for parts of the system that aren’t prototyped.

These validation exercises should be completed and the stakeholders should concur that the specifications are correct before one baselines the specifications, including requirements.

34.9.1 Connecting requirements and implementation artifacts

People must be able to navigate from a requirement to its associated implementation artifacts and vice versa. The people implementing a part of a system according to requirements need to be able to quickly and accurately find the requirements that they need to comply with. In the other direction, the people verifying requirements must be able to find the artifact or artifacts that implement a particular requirement.

The approach to organizing systems artifacts that I advocate here, which organizes many systems work around a hierarchical component breakdown structure, is designed to meet this need conveniently. The set of requirements that apply to some component are implicitly connected to other specifications and the implementation of that component because they are all organized by the same component names and identifiers.

One can also explicitly label artifacts with component identifiers or requirement ids. For example, verification test specifications are associated with specific requirements, so the test specification needs to be labeled with the requirement ids that it applies to.

34.10 Verification

Verification is the process of showing that the implementation of the system, or parts of it, complies with the requirements.

Verification involves gathering evidence that every requirement is satisfied by the implementation.

There are four general methods used to verify the implementation’s compliance:

• Inspection: review of the implementation (source code, board designs) to manually check that the implementation complies
• Test: define and perform tests on the implementation that check compliance. Many requirements require a number of tests in order to show that the implementation complies given all reasonable inputs or environment conditions
• Demonstration: show the implementation working as defined
• Analysis: perform a static analysis on the implementation to gather formal evidence that the implementation complies

Inspection is verification by having people review parts of the implementation to check that it complies with a requirement. The inspection review should be performed by people who did not implement that part of the system, so that the reviewers are not misguided by preconceptions (“I’m sure I implemented this correctly”).

Some inspections are particularly simple. Consider a high-level requirement that is the source for a few lower-level requirements. In many cases, the high-level requirement is satisfied when the lower-level derived requirements are all satisfied. In these cases inspection becomes a simple matter of checking that the derived requirements are all satisfied. The rationale associated with the derivation or with the high-level requirement should indicate when this situation applies.

Test and demonstration are similar. Testing is generally more exhaustive, and necessary lower-level components. A single electronic component, for example, might be operated across all the specified thermal, vibration, and atmospheric environments it must handle. Demonstration is less exhaustive, and used to verify top-level system objectives. A prototype spacecraft radio transceiver might demonstrate that it can communicate with ground stations from a similar orbit to where the final spacecraft system will operate.

Some requirements cannot effectively be verified by test or demonstration, and must be verified using analysis. This occurs when one is verifying a negative condition: the verification must show that the system will not perform some action or be in some condition at any time. Providing evidence of the absence of some condition is a long-standing scientific and engineering problem because proving the presence of some condition is relatively easy—demonstrate it happens in one case and that’s sufficient—but showing absence often requires exhaustive search. These verification problems often arise in safety and security requirements, where unsafe failures must be rare (e.g. no more than once in 10⁹ operating hours) or a system must resist a class of attacks (showing that no attack of that class will succeed).

Each requirement should have an associated verification specification. The specification should lay out what steps must be taken to determine whether the implementation is correct or not. A verification specification is often complex—many pages of documentation for a three-line requirement.

Verification status is a measure of how well the implementation matches the specification, including requirements. In practice this means how well a version of the implementation complies with a version of the specification, as both implementation and specification evolve over time. This means that, during design or implementation, there is no one single “verification status” that can be tracked: with each new update to the implementation, the verification status changes. Some practitioners and tools make the mistake of tracking verification status only in terms of requirements: which requirements have been satisfied by the implementation? This leads to project management errors when a change is made to the implementation that improves the implementation in one area but causes other parts of the system to go out of compliance—a common occurrence while in the middle of implementation using iterative approaches.

34.11 Limitations of requirements

Requirements have limitations. Writing a good specification for a system means understanding these limitations and addressing them in one way or another.

One limitation is that requirements are written in natural language. Human language is notoriously difficult for pinning down precise meanings, even within a single group of people. Specifications, including requirements, are used to communicate between different groups of people with different outlooks, experiences, and jargon. This makes it hard to write requirements that will be interpreted the same way by all of the people involved.

The limitation of natural language can be partly mitigated using a couple of techniques. One is to maintain a glossary that defines words or phrases that have specific meanings in the specification beyond common understanding. The second is through social cohesion: having enough people from different groups interacting and discussing the system so that they evolve a common understanding of the meanings of things.

Precision is another limitation. Some specifications can be clear and simple in mathematical notation, while they are hard to follow in prose. (Consider expressing Newton’s law of gravitation as an equation versus in prose.)

A third limitation comes from requirements being single statements. Sometimes the specification needs to encode a complex, multistep activity. Each of the steps might be encoded as an individual requirement, but it is awkward and hard to understand. Sometimes the better answer is to write part of the specification in a different form—a flowchart, a state machine, or a set of equations.

As a result, requirements are only one part of the total specification. They cannot do the entire job of recording the full specification of the artifact in question—but they are often the most flexible way to organize most of the specifications. Be prepared to supplement textual requirements with other kinds of specification to get the whole job done.

34.12 Working with requirements

This chapter has mostly covered what requirements are. This section touches on what one does with them and how they evolve over time.

Requirements will change continuously over the life of a project. The rate of change will be high at the project’s beginning, when the team is trying to sort out what the system should be. The rate of change will increase after the high-level system purpose is sorted out and as the design work proceeds in parallel on different components in the system. The rate will taper off as the design and implementation become more mature, with occasional bumps as people find problems with the specifications, or as stakeholders request changes. Ideally the rate will reach zero when the system is ready to go operational, but even while in use people will find changes they would like to make.

Detailed requirements are expensive to develop and maintain. They encapsulate the complexity of how all the parts of a system are interconnected. They require effort to develop in the first place, involving checking for consistency and feasibility across large parts of the system. Changes later involve even more effort, especially if the changes involve reorganizing specifications that have already been developed.

This leads to a tension: changes will always happen, especially with modern, flexible systems, but the cost incentivizes developing all the requirements at once and then freezing them to minimize the cost of change.

This tension is unavoidable, but there are things one can do to reduce the difficulty.

• Don’t start finalizing requirements too early. Work with a sketch version of the main points while exploring the concept.
• Develop detailed requirements for a part of the system hand in hand with prototyping the components that make up that part of the system. Most teams learn a lot from prototyping exercises; what they learn translates into design changes and in turn into requirements.
• Start the processes for communicating about specification changes early in a team’s development, so that people have developed the habit of talking to each other about changes that might affect others before major, disruptive changes come along.
• Use the right tools that help the team coordinate developing and changing the requirements.

34.12.1 Supporting the life cycle

The requirements for a system—and indeed all the specifications for the system—grow and evolve over time. The times and ways when requirements change depends on the development process a project is using. However, all these processes share some tasks in common.

34.12.2 Who works with requirements

Many people generate or use requirements during the lifetime of a project. These include:

• The product or mission managers who define the system’s objectives and review and approve the top-level system requirements
• The engineers who develop, revise, and maintain the requirements
• Change management people who oversee the process to baseline and release consistent, committed-to versions of specifications
• Designers and implementers who build components following the specifications
• Engineers who design how different requirements will be verified
• People who verify implementations against the requirements
• Managers who track the progress of implementing requirements and the progress of verifying components
• Vendor managers who oversee the process of writing requests for proposals, evaluate vendor offerings, and oversee the acceptance verification of artifacts from vendors
• Vendors who design and build components according to requirements
• Contract specialists who incorporate requirements into vendor contracts
• Technical writers who develop operational and training manuals based on the requirements
• System operators who use the requirements to understand how the system works in operation

34.13 Tools

The right tools make working with requirements much easier and more accurate. However, different requirements management tools are designed to support different styles of requirement writing and use, so you need to choose tools that match how you will write, organize, and use requirements.

Here are some questions that can help you evaluate requirements management tools.

• Do the tools support the writing style and requirements organization strategy you use?
  • If your project is using hierarchically-organized requirements, does the tool support that?
  • Do the tools provide a way to organize requirements for one component into sections?
  • Do the tools support organizing requirements in the way your project organizes them? If you organize requirements by component, do the tools support that?
• Do the tools provide ways to trace top-level requirements from external sources, like policies or standards documents, that are the source for those requirements?
• Do the tools support tracing the derivation relationships among requirements?
  • Do the tools allow derivation among requirements within one component?
  • Do the tools allow mutual relationships between two components, when those two components have mutual dependency?
  • Do the tools provide ways to visualize the graph of derivation relationships?
  • Do the tools allow one to record a rationale for derivation relationships, in addition to rationales for individual requirements?
• Do the tools support the relationship between requirements and implementation artifacts or other documents?
  • Do the tools provide a stable identifier for requirements?
• Do the tools support reviews and baselining, or other versioning control mechanisms?
  • Do the tools support the ability to create a non-baselined, work-in-progress version of some requirements?
  • Do the tools provide a way to see the differences between a baselined version of requirements and a work-in-progress version?
  • Do the tools enforce a review and approval process?
  • Do the tools help notify those who are affected by a change and who thus should provide a review?
• Do the requirements tools integrate with other tools that support verification?
  • If the requirements change, do the tools make it clear what requirements must be verified anew?
  • If the implementation evolves, do the tools allow for verification results to be associated with a version of the implementation and not just with the requirements?

People will use the requirements management tools to perform a number of tasks. You should evaluate how well requirements tools support these activities.

• Writing new requirements: being able to quickly sketch out a set of requirements for some new component or some new function, and then fill in the details to complete a first draft of the new requirements. Ease of writing and editing is a key complaint about many requirements management tools.
• Reviewing and updating requirements: when someone requests a change to the system design or objectives, being able to find what things need to change and then being able to revise the requirements conveniently.
• Managing review, approval, and baselines: at some milestones, reviewers will need to see what requirements they should review, support them in the process of discussing the requirements, and tracking issues that are found until they are resolved. With some milestones, a version of the requirements will need to be approved (or not) and baselined.
• Performing requirements analysis: people will need to perform the analyses listed in the Analyzing requirements section, including checking that the design is complete, minimal, and consistent.
• Validation: people will need to review the requirements against the original mission or project objectives to see if the system will meet stakeholder needs. The reviewers are generally going to be independent reviewers who have not been using the requirements tools along the way. The tools need to support the reviewers determining whether the requirements are satisfactory, and tracking issues that are found.
• Verification: some people will need to develop tests or analyses to perform verification. Other people will then need to perform verification on system implementation artifacts, and track the status of how well the implementation is complying with requirements.

Chapter 35: Models

Chapter 36: Interface definitions

Part VIII: Design

• design practice XXX define this
• safety design and analysis
• security design and analysis
• design checking

Chapter 37: Design introduction

37.1 Purpose

Previous chapters introduced how to work out what a system or a component should do, by determining what the objectives are for it and then turning those objectives into a specification.

The next step is to design the system or component that will fill those needs.

A design for a component provides a simplified model of how the component will achieve the behaviors, qualities, and structure laid out in its specification. The design is not the full details of how it will achieve those things, or a detailed implementation. The design is a plan for how the component will be built, at a high level; it records the high-level decisions about how the component will be implemented without actually being the implementation.

“Design” is an activity that lacks sharp boundaries from other development activities. On the one hand, it responds to the objectives and specifications that have been developed for the thing being built; on the other hand, the act of designing usually reveals gaps in the specifications that lead to feedback that causes people to update the specification. Specification and design proceed recursively as a system is built, where the act of designing one component leads to writing specifications for its subcomponents.

“Design” also lacks a distinct boundary with “implementation”. Indeed, the boundary between the two varies by convention in different disciplines.

• In electrical engineering, a “board design” is a detailed mechanical design, choice of components, and layout of components and circuits—what one might classify as implementation. A higher-level design for a board would include things like the most important components (e.g. chip, SOC, discrete electronic components) that will be used, the kinds of interfaces, connectors, or cables that will interface the board to others, along with the record of a rough physical layout that shows that an implementation is likely possible. This higher-level design guides the board designer to create a board design that is ready to be assembled.
• In software, a design typically consists of high-level decisions such as where the software will be deployed, the structure of how subcomponents communicate with each other and with outside components, the state and operations that are to be implemented in the component, and behaviors it will perform. This design leads to a software engineer writing the specific code that implements the design.
• In architecture or mechanical engineering, a design records the general decisions about the shape or layout of the structure being built, how it connects to other components, and key design choices like materials or colors. This leads to detailed mechanical drawings that incorporate all the supporting details needed to build the structure.

37.1.1 Defining “design”

Given the diversity of ways the word “design” is used, I will define what I mean by the term in general.

A design is:

• A high-level record of the decisions made about the structure, state, and behaviors of a component or system, and how it meets its specification
• A record of how the system or component connects to things outside itself, including physical connections, data or control, or energy transfer
• A record of how the system or component breaks down into subcomponents, and the roles or specification of each
• A guide to the reviewers and implementers that helps them understand the component’s structure and function
• Simpler than the detailed implementation of the component, so that the design explains the implementation
• An abstraction of the implementation that allows one to analyze the component (for safety, security, performance, or meeting objectives) at a reasonable level of effort, when doing the analysis using a detailed implementation would be too complex

A design is not:

• Detailed enough directly to support assembling and operating the component or system
• The specification, which records properties of a component without saying how it should be designed to provide those properties
• The implementation, which is has enough details that the actual component or system can be assembled, integrated, tested, and deployed

In some projects I have used the term “design model” for the design, to emphasize that the design is a simplification and explanation of the most important aspects of the component’s implementation.

37.1.2 Contents of design

There are several kinds of information that should be recorded in a design.

• The components that make up the system, with names or identifiers for each. This can be thought of as the catalog or table of contents for the system. Every component in the system should be included, whether it is built from scratch for this system or brought in from some supplier. Having a list and names allows people to identify what they are talking about, and it enables checklists for making sure everything is done.
• The structure of how each component breaks down into subcomponents. This identifies how the pieces of the system are grouped, which helps people navigate through the design to find the parts in which they are interested. (This also often reflects how the teams building the system are organized.)
• How each component interfaces and interacts with other components. This information provides a map to the other components that will be directly affected by this component’s behavior or structure, and vice versa. It provides the information needed to map out more indirect ways that other components can be affected or affect this component.
• The high-level state, behavior, and structure of each component. This is the core of the plan for how the component will implement its objectives. The state information might include modes of operation, information the component stores, or physical configurations. The behavior is how that state can change: how the component can change from one operation mode to another, or how the component can change its physical configuration. The structure might be the shape of a mechanical component, the modularization of a software component, or the major chip components of an electronic component.
• How each hazard or objective that has been identified for a component is addressed in the design.

All of this information should be annotated with a rationale for the decisions that led to the particular design.

37.1.3 Purposes of a design

Why should one take the deliberate and separate step of putting together a design for a system or component, rather than just implementing a component directly based on its specification?

For an exceptionally simple component, one can skip design and just implement the component—but the component must be truly simple, completely understandable from its implementation, involving no significant design choices, and with no future need to change the component, for this to pay off in the long run.

The value of an explicit design comes partly from its abstraction and simplification, and partly from being done mostly before putting together the detailed implementation.

• The effort of design provides time to reflect on decisions before committing to designs.
• A design effort allows incremental design that allows one to balance all of the important design constraints before going into detail on any one aspect of the design.
• The design provides a guide and explanation for the component.
• The design provides a place for people to write down the rationales behind the decisions they make.
• The design supports analysis, which usually feeds back into the design before spending resources on implementation.
• Designs for alternative approaches for implementing a component support comparison and decisions.

37.2 How designs are used

As noted above, a design enables communication among multiple people, across different times, and for different purposes.

37.2.1 Design leading into implementation

As well as all the uses listed above, the developer uses the design as a guide for the implementation. The resulting implementation must be consistent with the design: having the same structure and behavior, including all the functions in the design, and including no functions not in the design.

The developer or implementer must be able to understand the design to build a component that matches the design. The developer must also be able to check that they understand the design properly, so that there is a way to catch misunderstandings. A good design uses consistent structure, terminology, and diagrams to aid understanding. It provides a glossary of terms that may have multiple meanings to define how they are used in the design.

Developers will find problems with the design as they proceed through implementation. They may find ambiguities, where the design is unclear or where the design does not address some important condition. The developer may find errors, where the design is inconsistent internally or with its specification. The developer may find that parts of the design aren’t feasible to implement. All of these problems need to be fed back to designers for clarification or correction.

When the design changes, the developer needs to be able to identify what parts of the design have changed so they can change the corresponding implementation. The change might come in response to feedback from the developer, or evolution of the design to address changing needs or broader system fixes. This can be supported by using tools that track design versions and highlight design changes between versions.

Finally, the developer must be incentivized to follow the design (or provide correction feedback) as they implement the component. This includes having the designer and independent people review the implementation to compare it to the design. If they find that the design and implementation are not consistent, they must decide on how to change the design, the implementation, or both in order to achieve consistency. The component implementation should not be accepted as complete until they match.

37.3 Design artifacts

The artifacts that record the design enable all the usage cases listed above. The key functions they need to fill include:

• Organizing the design of the system and each component in a way that people can find the parts of they system they are looking for, and understand the context of those parts.
• Recording the structure, state, behavior, and shape of each component so that people can build a corresponding implementation or analyze the design to check whether it meets needed properties, including safety and security.
• Recording the rationale or explanations for why the design is what it is.

37.3.1 Supporting infrastructure

The designs for a system need to be available to everyone associated with the project, so that they can use the design to learn about the system and navigate through it.

An ideal solution provides a “single source of truth”: a user can go to one place and see all of the information about the system. The ideal solution also ensures that the user always sees a single consistent version of all the information. To the best of our knowledge, at present there are no systems that completely meet this ideal. However, there are ways to come close by integrating multiple tools and applying conventions to how they are used.

The infrastructure for maintaining designs needs to, at minimum:

• Store all of the design information, organized according to the names or identifiers for each part of the system
• Support multiple versions of the design, where one version is the current approved baseline, some versions are outdated and no longer useful except for historical reference, and some versions represent works in progress that are being developed or are alternatives, and that have not yet been completed and made part of the approved baseline. Note that software repository systems have evolved a number of useful conventions about how to maintain and name these versions; the version management capabilities for a design repository should be at least as capable as those.
• Support finding the differences between versions. When a design changes, a reviewer or developer will need to understand what they need to look at to understand the change. Tools that expose all differences between versions reduce the chances that some change will be overlooked.
• Support integration and tracing between specification and design artifacts. The design of a component is in response to the specification for that component, and the infrastructure should make it convenient for a user to see how the design maps to the specification and vice versa. Similarly, the specification of a subcomponent responds to the design of the component it is part of, and the infrastructure should help users understand that connection.
• Support reviews and approvals. Each design will begin as a work in progress, and then progress until it becomes the approved baseline (or until the work in progress is abandoned). Being able to track what designs need to be reviewed by whom, track the feedback from those reviews and corresponding updates, and tracking the approval of a design is error-prone without tools that support the process.

37.3.2 The artifacts

The following sections list the key artifacts that should be part of a design. Later chapters will detail these artifacts.

37.3.2.1 Breakdown structure

The breakdown structure consists of the hierarchical relationship of system, components, and their subcomponents recursively. It gives a name or identifier to each component, and provides the index or table of contents to the parts that make up the system. See ! Unknown link ref.

37.3.2.2 Control structure and other large-scale behaviors

A complex system will have behaviors or structures that cross multiple parts of the system, and don’t neatly fit within a single hierarchy of components. There are two important examples of these behaviors to document.

The first example is behavior or activity sequences that show how different parts interact with each other. These are sometimes documented as UML or SysML activity diagrams, which show how control or data pass among components, and how different components take actions in response to those. The point of these patterns is to show how components work together, which informs the interfaces, actions, and states that the components involved in the activity must support.

The second example is the hierarchies of control that operate in the system. These document how one part of the system controls the functions in other parts, including how some components provide sense data to drive the control logic, and how the control logic in turn sends commands to other components to effect control actions. Documenting and analyzing these control systems is an essential part of some safety and security process methodologies, such as STPA [Leveson11].

37.3.2.3 Details of each component

Each component in the system should have its own design. This is the primary content about individual components, as opposed to how components work together.

A component’s design can be represented in many different ways. However, it is easiest for users if all designs follow the same general format so that they know how to find particular kinds of information within every design.

All designs should include:

• An identifier and name or title for the component
• The version of the design and its status (in progress, obsolete, baselined)
• The position of that component in the breakdown structure (that is, what it is a subcomponent of)
• A short description of the purpose of the component, to aid people coming later to understand the design
• Information about the states, behaviors, interfaces, and environment for the component
• The decomposition of the component into subcomponents, if any
• A list of the artifacts that implement the component

Each component’s design should include rationale: the reasons why different design choices were made. This information helps those who must come along later to review or update the design.

In some cases, not all of this information can be represented in one way or in one tool. For example, for electronics designs the best way to represent some information will be in a CAD drawing that is maintained in a separate tool from the rest of the design information. In these cases, there should be unambiguous references from the main design to the CAD drawing and vice versa, and the versioning in the main design should be reflected in versioning in the CAD tool.

37.3.2.4 Safety, security, and other analyses

Part of the reason for developing a design—as a simplified model of what will be implemented—is to enable analysis of the design’s essentials. These analyses address whether the design will meet aspects of the component’s specification. These can include safety and security, as well as meeting business objectives, regulatory requirements, performance specifications, or resource budgets.

As I will discuss in the next section, it is recommended practice to develop these analyses incrementally in parallel with the design itself. In this way, a rough analysis of a rough design can provide quick, early feedback that will guide the design toward meeting its specified properties as it is developed in more detail.

These analyses become an important part of the record of a design once complete. They provide an extended rationale for why the design is the way it is. They may be needed to answer to external stakeholders, including regulators or courts of law, when it becomes necessary to provide evidence why the design is acceptable. The analyses also help people who must later evolve the designs to understand both the constraints on what they can change, and where they have freedom to make changes without invalidating the safety or other properties of the design.

37.4 Developing designs

As a matter of principle, the design for a system or component should be done after its objectives and specification are done, and before its implementation. Similarly, the design for the components in a system should proceed top down, starting with the system as a whole and proceeding to lower and lower level components. When the design of one component depends on the design of another, the two should be designed together.

These principles often lead people to conclude that systems should be built using a waterfall-like process, where everything is specified before design, everything designed before implementation, and so on.

Real projects are not so simple. I have never observed a project that actually used such a process, even when they tried to. This is because every complex system I have encountered is not fully and accurately knowable in advance. One can write a set of specifications that turn out to require some impossible component design. One might miss some important system objective when developing the initial system concept because the customer was not able to conceive of system operation until they could see part of the system in operation, or because the customer’s needs change. An initial design may be invalidated because a supplier discontinues an essential part. Some part of the system may require significant investigation or research before one can find a feasible way to approach its design.

All of these situations lead to cases where the specification, design, and implementation of the system does not proceed in a tidy one-way sequence through the waterfall stages. Instead, part of a component’s specification gets worked out, and some tentative design goes ahead using that part of the specification gets worked out. Or multiple possible design approaches are defined, and then someone proceeds to build simple prototype implementations of two or more of them to compare their feasibility. Or the design for a component must change, leading to a change in implementation. All of these may be happening in multiple parts of the system at once.

At the worst, all this change happening all over a system can lead to chaos where people working on different components are working to incompatible specifications or designs and building parts that will not integrate into a system. Project management may not be able to determine how much progress has actually been made on any part of the system, and thus be unable to detect when there are schedule or resource problems.

Therefore while the simple waterfall model, which organizes the work on a system, is not feasible, there is still a need to organize development work.

37.4.1 Applying general principles, flexibly

The principles I started with are good ideas in general, when used flexibly.

37.4.2 Additional principles

Chapter 38: Breakdown structure

The component breakdown, or breakdown structure, is the way to name and organize all the components that make up a system.

38.1 What is the component breakdown for?

The component breakdown organizes and names all the pieces in the system. It serves three main purposes:

• It provides a master list of all the components that need to be designed, built, and tested to make up the system
• It provides a unique identifier for each component, so that every piece of the system can be referred to
• It provides an organization for all the documents and artifacts that make up the system. In this role, it provides an index or table of contents that helps people find information about the system and its components

These purposes lead to a few objectives that a breakdown should meet.

• The breakdown should be complete. It should include all the major components that people will be working on.
• The breakdown should reflect how people naturally think about how components relate to each other. People should be able to navigate through the breakdown structure accurately to find information.
• The breakdown structure should result in identifiers that are easy to use. The identifiers will be written down in many different places; they will be embedded in different artifacts to link them together. Identifiers that are too long or too easy to mis-copy will cause difficulty for users.

38.1.1 Component breakdown versus work breakdown

Some institutions, notably NASA [NPR7120][NASA18] and other parts of the US Federal government [DOD22], specify the use of a work breakdown structure (WBS) in project management and systems engineering. A WBS as used in those projects is different from a component breakdown structure as defined here.

A WBS is oriented toward project management, not systems engineering. It is focused on defining the work to be done (hence the name) rather than the items or components being built by the work. From the NASA WBS Handbook [NASA18, p. 35]:

Other project management methodologies define a work breakdown structure as, in effect, a checklist of the kinds of work that may be required for a system, feature, or component. McConnell discusses using a generic work breakdown structure in estimation to ensure all the effort involved is accounted for [McConnell09, Table 10-3].

This difference in intent leads to two major differences in the contents of a WBS compared to a component breakdown. The first is that a WBS includes work items that are not product artifacts. The standard NASA WBS, for example, includes project management, systems engineering, and education and public outreach branches of the work breakdown tree [NASA18, p. 47]. Given that part of the goal of the WBS is to organize resources and budget for a project, that’s an appropriate choice. The other difference is that some people break a task for building a component down into multiple revisions or releases. For example, a “motor control software” component might have subitems “prototype”, “release 1”, and “release 2”, recording the phases of work done to develop that software package.

The component breakdown structure presented in this chapter is narrower in focus than a WBS. The component breakdown lists only the things that are being built. It must be complemented by other engineering and management artifacts to provide everything needed to run a project.

38.1.2 Component breakdown versus other views

The component breakdown is one of several views into the system’s design and specification. The component breakdown has only two purposes: listing all the components and giving them unique names, and providing a structure that people can use to navigate through the components to find one they are looking for.

The component breakdown is not for expressing other facts about components and relationships between them. There are other views and other breakdowns for representing that information—and for doing so in ways that are better suited to the specific information that needs to be explained. For example, a network or wiring diagram does a better job of illustrating how multiple hardware components are connected together. Mechanical drawings are a better way to show how components relate to each other physically. Data and control flow diagrams, perhaps realized as SysML activity and sequence diagrams, are better suited to expressing relationships between software components.

38.2 Basic concepts

When developing a component breakdown, the first question to be settled is: what is a component?

First, a component is something that people think of as a unit. Terms like “system”, “subsystem”, or “module” are all clues that people think of a thing as a unit. More generally, a component is something

• That can have a defined boundary of what functions or parts are part of the component, and what is outside, and
• That has a physical or virtual reality; it is something that needs to be built or acquired.

Components do not have to be atomic units. Systems have subsystems; components have subcomponents. For example, the electrical power system (EPS) in a spacecraft is a medium-level component in a typical breakdown structure. It is part of the spacecraft as a whole. It is made up of several subcomponents: power generation, power storage, power distribution, and power system control. Each of those subcomponents in turn have constituent components themselves: for example, power generation has solar cells, perhaps arrays that hold the cells, perhaps some other power generation mechanism.

This illustrates the general pattern for the breakdown structure. The structure is a tree, with the highest-level component being the system as a whole. The system as a whole is typically not just a vehicle or box; it is the entire mission or business on which a vehicle is part. Underneath the whole system come the major component systems. For a spacecraft mission, this might be the spacecraft, ground systems, launch systems, and related assembly and test systems. The next level of components are the major subsystems. The structure continues recursively until reaching components that are the smallest that are sensible to model using systems tools.

The recursive process of defining smaller and smaller components ends when there is a judgment that further subdivision won’t help the systems engineering process. In practice, for example, continuing the breakdown structure all the way to individual resistors and capacitors on a printed circuit board is too detailed to be useful for systems engineering tasks.

Some criteria I have used for deciding when to continue subdividing a component into subcomponents include:

• Does the state of the component separate into multiple independently-acting parts, or not? If the state of the component can easily be modeled as a single state machine, then it probably does not need to be refined; if the natural modeling is as a collection of independent, interacting state machines, then it should be refined.
• Is the component physically a single physical unit? Or is it fundamentally a collection of smaller physical components?
• For software, is the component treated as a single unit? Or does this project assemble the software component out of other parts?
• How large or complex are the tasks to design, build, or test the component? If the component can be designed and built by one person or one vendor, then there is less incentive to split it into subcomponents than if multiple people or organizations must work together to design and build the component.

Some examples:

• An aircraft. This is a high-level component in a breakdown structure for a project that is about designing and building a new aircraft model. In that project, the aircraft will have components like body, wings, propulsion, fuel, communication, and so on. If, on the other hand, the project is to design and build an air traffic control system, each aircraft is likely best treated as a low-level component that is not further broken down because all the aircraft in the airspace have roughly similar functions and behaviors, and the air traffic control system is concerned primarily with sensing those aircraft and guiding their flight.
• An aircraft’s body (fuselage) structure. This is usually a middle-level component in an aircraft system. It is part of the aircraft over all. It is made up of formers, stringers, trusses, and skin. Each one of those subcomponents is typically built separately and then joined together to make the aircraft’s structure. Each will have different mechanical constraints; there are likely to be different choices for the materials out of which each one is built. These are candidates for refinement of the fuselage as a whole into a collection of subcomponents.
• Infrastructure software, like an operating system. An operating system is a complex body of software; some operating systems contain several million lines of code. If a project is building an operating system, then the operating system as a whole will clearly need to be broken down into many subsystems. However, for a project that uses the operating system but doesn’t build it, the operating system doesn’t necessarily need to be broken down further: the team will obtain the operating system as a whole from a vendor and use it in its entirety without the team needing to make modifications to the operating system itself. For an aircraft project, for example, the team may buy a real-time operating system from a vendor. The team may need to build or separately obtain some of the related software components, such as a board support package and device drivers. In this case, the OS would be one component, and the BSP and drivers would be separate subcomponents–but there is no need to model the operating system’s virtual memory management system.
• A printed circuit board implementing a processing unit. This is an example that may or may not be worth breaking down into subcomponents. If the board (and the parts mounted on it) are treated as a single entity, acquired as a whole, and treated as a single unit for application software purposes, then the board need not be broken down further. On the other hand, many circuit boards implementing a processing unit today are complex systems: in one recent example, the board had a primary processor, a secondary control processor, a storage system, a cryptographic unit, and two different network communication units. While the board was built and delivered by a single vendor, separate software had to be written for each of those parts—and in some cases there was an option whether to populate some of the storage and communication parts or not. In that example, breaking the overall board into subcomponents was necessary.

38.2.1 Satisfying the objectives

1. Completeness. Completeness depends on the exercise of identifying all the components to run to completion. The hierarchical approach does not directly inhibit or support this objective. However, the hierarchical approach makes it easier to approach completeness iteratively: one can start with a high-level breakdown, and incrementally expand parts of the breakdown tree when one finds that some components need to be refined.
2. Supporting navigation. People generally talk about the structure of systems in a hierarchical way: system and subsystems and components and subcomponents and so on. This means that a hierarchical breakdown structure matches common usage (as long as the refinement into smaller and smaller components follows the common usage).
3. Usable identifiers. The hierarchical structure does support unique names for each component, as will be discussed later. The identifiers are usually not the most compact possible, because the identifiers reflect a path of names through the breakdown structure tree, similar to the way file systems and URLs organize hierarchical names. However, the hierarchical identifiers in practice have worked well as a readable and writable form of identifiers in other domains, including URLs.

38.2.2 Alternatives

The approach laid out here is fundamentally hierarchical, and reflects the way people usually approach breaking down a complex system—by a reductive approach that organizes parts into a hierarchy.

That is not the only approach to organizing the components. Mechanical and electrical engineering systems often use a more-or-less flat space of part numbers to identify components. The specifications for each part can have attributes, and the attributes allow one to search for a desired part.

A flat part number approach works well for low-level, physical components. A 100 ohm resistor can be used in many different components; there is little value in giving a different name for its use in one place on one board and a different name for a second place on that board, or on a different board. Similarly, when manufacturing many instances of a vehicle, using a part number to identify the part in an assembly works well.

I have generally not used a part number approach for higher-level systems activities, however, because the uses are not the same. During design, each component that systems engineering deals with is generally unique.

38.3 Component identifiers

A component’s identifier provides a unique way to refer to that component. It is like the address for a building: it allows one to find the component (or its specifications), but does not by itself convey much more information. The keys are that the identifier be unique, and that people can use the identifier to find what they are looking for.

The pathname is the long-standing practice for creating identifiers for elements in a hierarchy. This is familiar from file systems and URLs: the path /a/b/c/d refers to a file or object named “d”, which is contained in “c”, which is in turn contained in “b”, which is part of “a”, which is one of the top-level objects or folders in the system. While the object name “d” is not necessarily unique (there can be another object /a/f/d, for example), the path as a whole does give a unique identifier for the object or file.

This approach applies to the identifiers for components in a breakdown structure as well. The names in the path are typically separated by a slash (/) or period (.).

The names of each component in the tree can be abbreviations or short words describing the component. Both work well; the choice is primarily a matter of style. When there are commonly used abbreviations for some components, it is reasonable mix and match abbreviations and longer names. For example, a spacecraft’s computing system is often called the CDH (command and data handling); attitude control is the ACS (attitude control system); and the electrical system is the EPS (electrical power system).

Some examples from a fictitious spacecraft system:

Long component identifiers can become a problem. Long identifiers are harder to type than shorter ones. Sometimes there are limits on how long an identifier can be; for example, if one is recording information about components in a spreadsheet and putting each different component on a different sheet, most spreadsheet packages have limit on how long a sheet name can be.

The length of an identifier is driven by how deeply the breakdown structure tree goes. The path name for a component six layers down in the hierarchy will be much longer than the path name for a component in the third layer. This suggests that one should try not to make the component hierarchy any deeper than it needs to be.

38.4 Viewing the breakdown structure

Many people find a visual representation of the breakdown structure helpful for understanding it. Here is a drawing of an incomplete breakdown structure for a simple spacecraft:

It is worth finding tools that can show this kind of visual representation of the breakdown structure.

38.5 Context and relationships

The breakdown structure provides the fundamental organization for most systems engineering artifacts. This means that the structure chosen for the breakdown will affect how most other parts of a specification are organized.

Each component named in the breakdown has a specification. The specification includes information like

• The purpose and scope of the component
• Its requirements
• Its state and behaviors
• Its interactions and interfaces with other components

When two components interact, the interface between them must name which components are involved. The specifications for each component must indicate what data or control they will be sending and receiving in the interaction.

The identifier for a component provides a way to express a reference between implementation and test artifacts, like source code or drawings, and the specifications to which they should comply.

The breakdown structure affects almost everyone working on the project. This includes:

• Systems engineers develop the breakdown structure
• Every engineer and developer users the breakdown structure to find information about the components they will work on or that they will interact with
• Project managers use the component breakdown as a basis for defining development tasks and tracking their progress
• Contract managers use the breakdown structure to identify deliverables that vendors might provide

38.6 Advice

38.6.1 Evolution

The understanding of the system evolves gradually from the initial concept to the time that a final product is delivered (if indeed there is a final product). At each step of this evolution, the understanding of what should be in the breakdown structure and how it should be organized will change.

Because the breakdown structure is central to many other processes and artifacts, a change to the breakdown structure will result in changes to potentially many other artifacts. The cost of the change grows as the size of the breakdown structure tree grows.

Don’t try to build an elaborate and complete breakdown structure too early. At the beginning, while still working out the basic concepts of the system and its structure, just sketch out the first level of the structure—and try out several potential structures until one appears to match the system’s objectives. Often the main structure will be suggested by common practice for similar projects: the automobile industry has a common, vernacular breakdown of cars and trucks into common subsystems, for example.

In general, it is best to keep a branch of the breakdown structure shallow as long as there is significant uncertainty about how that part of the system will be designed. In an aircraft, for example, the propulsion system should be left unrefined in the breakdown structure until the team has settled on the general approach to propulsion—will it use turbofans, turboprops, propfans, electric rotors, or some combination? The broad choice can typically be settled early in concept development by working out the concept of operations and determining what capabilities, performance, and physical layout will meet the aircraft’s operational needs. Once the general architecture has been decided, then one can refine the propulsion system by adding a layer of components for each engine or other major unit involved in propulsion.

38.6.2 Depth

The point of the breakdown structure is to help people find and refer to components. The breakdown structure should reflect common ideas of how a system breaks down into components, and should result in short, easy-to-use identifiers. The breakdown structure should focus on these capabilities and not be drafted into serving other purposes.

Consider the breakdown structure for all the sensors that provide information to an autonomous vehicle. One way to organize the sensors is to create a general “sensors” component, and then include all the sensors as children of the general sensors component. Another way is to break the sensors down first by general type (camera, lidar, radar, sonar, microphone), then by general location of the sensor on the vehicle (front, left, right, top, back), and then by the specific sensor unit. In this example, the first approach leads to a shallow and broad breakdown structure; the latter example leads to a narrow and deep structure.

In general, a shallow, broad breakdown structure will meet these objectives better than a narrow and deep structure. There are a few reasons for this.

• The identifiers for sensors will be shorter. The shallow structure might name a particular camera “sensors.leftcam” while the deeper structure might name it “sensors.camera.left.camera1”.
• The broader structure serves the purpose of helping people locate a component better. In the broad structure, a developer knows that all the sensors are under the “sensor” component; they can navigate to the sensor component and then find the particular sensor they are looking for in the list of sensors. In the deep structure, the developer must navigate to sensors, then to cameras, then to the location, and then find the sensor. If the developer is looking for a particular type of camera and doesn’t know where cameras of that type are located, the extra layers pose extra work.
• The shallower structure handles evolutionary change more easily. If a project uses the deeper approach, then determines that the layering structure isn’t working as well as expected and the structure needs to change, that will lead to changing the identifiers for many components—which in turn leads to finding and updating identifiers in many other artifacts where the identifiers have been written down. In the shallow structure, there is no structure organizing the sensors and nothing to rearrange.

This leads to a general principle. The breakdown structure should be used only for providing a unique name, and not for embedding a taxonomy or search attributes. The tools that people use to navigate through the breakdown structure and its related artifacts, like specifications, should provide search mechanisms that let someone find a component by attributes. Embedding extraneous information, like a location attribute or model number or power requirement in the name will just make the names longer, harder to use, and less resilient to change.

38.6.3 Multiple fit

The hierarchical, tree-structured approach recommended here makes each component part of exactly one parent component. It does not accommodate components that have more than one natural affinity to parent groupings.

Consider a radio transceiver that is used to communicate between aircraft, such as the ADS-B systems used for collision avoidance. This transceiver could be categorized multiple ways. It is part of the aircraft, but it is also part of an air traffic management safety system. The transceiver within the aircraft is part of a communication system, but it is also a part of the flight control system and intimately connected with human interface components on the flight deck. The transceiver, in other words, is part of several different groupings of components, depending on who is looking and for what purpose.

There is a fundamental tension between simple organizing structures, like a tree, and the richer relationships that elements of a system have with each other. For an excellent discussion of this, see Alexander’s essay on trees as a structuring approach for cities [Alexander15]. In that essay, Alexander proposes that a lattice structure is a more appropriate model for organizing urban structures. In his account, a tree-oriented description of a city fails to account for the ways that a house can be both a place for a family to live as well as a node in a social network and a place of work; in each of these roles, the house is related to different buildings or locations in the city.

The systems engineering approach presented here addresses this problem by separating naming or identity from the complex relationships that each component actually has. The breakdown structure only tries to give a name to each thing, like the address for a building. The relationships, functions, requirements, and everything else that goes into defining a component are all left to other artifacts, such as the component’s specification and models of the components.

This means: don’t try to make the breakdown structure do too much. When a component fits into multiple categories, pick the one that seems most natural for most users and leave it at that. Other artifacts and tools will address greater complexity.

38.6.4 Not by function

The breakdown structure is for organizing components: things that are built and that can be seen or touched (possibly virtually).

There is sometimes a temptation to try to organize system functions into the breakdown hierarchy. Don’t do that. The breakdown of function—and of the allocation of function to component—is a separate task that needs to be addressed by a structure that focuses on how functions are organized.

A better approach is to maintain the component breakdown and a functional breakdown separately, and maintain an allocation mapping that shows how different subfunctions are achieved by different components. The functional breakdown is often better reflected in the structure of how specifications or requirements derive from each other. See the chapter on requirements for more on this.

38.6.5 Keep related things together

Some projects have proposed organizing components primarily by some fundamental, nonfunctional attribute. One project was considering separating hardware from electronics from software from operational procedures at the top level, and then organizing components within each of those categories by subsystem. Another project organized components first by the vendor organization that was to implement the component.

These approaches make it harder for people to use the breakdown structure to find things. Consider an electrical power controller on a spacecraft. This has an electronic component (the board and processor that runs the power control function) and a software component (that makes the decisions about what to power on and off, and to report information to a telemetry function). Someone working on the power controller will generally want to know about both aspects. Requiring them to look in two widely-separated parts of the breakdown structure is inconvenient, and (more seriously) it increases the chances that someone will miss a component that they need to know about to do their work.

As a general principle, it is better to group components by how people naturally think of them as being grouped. Keep functionally-related components close together in the breakdown structure so that people find everything they need about something by looking in one place.

As noted above, this doesn’t always work. The breakdown structure will not be perfect because not everything in a system naturally falls into a hierarchical organization. But the more that like things can be grouped, the easier it will be for people.

38.6.6 Generic and reusable components

There is one special case of a component fitting into multiple places in a breakdown structure that deserves special treatment: generic and reusable components.

Consider an operating system. There may be multiple processors within a system that may all run instances of the same operating system. It is useful to have one specification for that operating system: there’s one product that is acquired from a vendor, there is one master copy kept somewhere, and so on. At the same time, that operating system will be loaded onto many different processor components in different subsystems.

One way to address this is to have a part of the breakdown structure for generic components, and then put an instance of that component in the places where it is used. The specification of each instance component can refer to the specification for the generic, with those functions or requirements that are specific to the instance added. This is an example of using the class-instance model from object-oriented programming to solve the problem.

38.7 Examples

38.7.1 NASA Work Breakdown Structure

The NASA project management process and systems engineering standards use a common WBS structure across all NASA projects. The use of the WBS is codified in a Procedural Requirement document [NPR7120], with details in an accompanying handbook [NASA18].

The NASA WBS is used as a project management artifact to organize work tasks, resources and budget, and report progress. The hierarchy must “support cost and schedule allocation down to a work package level” [NPR7120, p. 113]. A “work package” means one task or work assignment that is tracked, budgeted, and assigned as a single unit.

A NASA project’s WBS tree is rooted in the official NASA project project authorization, with its associated project code.

The first level of elements is defined by NASA standards, and each element has a standard numbering. The standard elements for a space flight project are: [NPR7120, Fig. H-2, p. 113]:

Note how this organization mixes technical artifacts (payloads, spacecraft, ground systems) and management activities (project management, safety and mission assurance, public outreach).

The NASA WBS is intended to be one part of an overall project plan document. The project plan also contains information like:

• The governance and authority for the project
• Resourcing
• Organization (team) structure
• Schedule and cost plans
• Safety and risk plans

38.7.2 MIL-STD-881 Work Breakdown Structure

This breakdown structure standard aims to provide a “consistent and visible framework” [DOD22] for communicating and contracting between a government program manager and contractors that perform the work. It addresses needs such as “performance, cost, schedule, risk, budget, and contractual” issues [DOD22, p. 1]. This kind of WBS is thus focused on supporting contractual relationships with suppliers.

The standard defines a number of different templates for different kinds of projects. It includes templates for aircraft systems, space systems, unmanned maritime systems, missiles, and several others.

The template for an aircraft system includes the following Level 2 items:

• System integration, assembly, test, and checkout
• Air vehicle
• Payload/mission system
• Ground/host segment
• Aircraft system software release 1..n
• Systems engineering
• Program management
• System test and evaluation
• Training
• Data
• Peculiar support equipment (support equipment specific to this air vehicle)
• Common support equipment
• Operational/site activity by site
• Contractor logistics support
• Industrial facilities
• Initial spares and repair parts

As should be clear from this example, this WBS template aims to address not just the design and building of a system but rather the operation of the entire program, including testing, deployment, and initial operation.

38.7.3 A simple spacecraft system

This is an example component breakdown for a simplified imaging spacecraft. The spacecraft uses solar panels to collect energy; it has a single imaging camera to collect mission data; it has a flight computer to run the system; an attitude control system to point the imager where needed; and a radio to communicate to ground. (The graphical version of this breakdown structure is included earlier in this chapter.)

This example only goes four levels deep. The actual breakdown structure would likely include at least two more levels, to represent, for example, different parts of the flight control software or subcomponents of the radio transceiver.

The example includes an example of a component that could fit in multiple places in the structure: the propellant tank heater. This is part of the thermal management system—its function is to keep the fuel in the propellant tank within a certain temperature range—but it is also part of the propulsion system. In this example the choice was to categorize it as part of the thermal management system.

Chapter 39: Component design

• what goes into a component’s design, based on Section 11.4

39.1 Form

39.2 State

39.3 Actions or behaviors

39.4 Interfaces

39.5 Non-functional properties

39.6 Environment

Chapter 40: Good design practices

• Modularity
  • Isolating high-interaction parts

• Hierarchy and composability

• Avoiding long distance

Chapter 41: Prototyping

- purpose of prototyping

- reasons to prototype

- pitfalls of prototyping

- good practices

– bounded effort

– explicit non-reusability

Chapter 42: Budgets

• Idea of budgets: that there is some amount of resource to be shared among a number of components (parts of the system)

• the problem to solve: use resource efficiently but not oversubscribed (not too heavy or too power hungry)

• Examples: simple
  • Power, constant source
  • Mass
  • Bandwidth or time

• Examples: complex
  • Power with variable generation (show powerstrip output)
  • Screen real estate, especially when modal
  • Fuel/Delta-v

• Techniques
  • Tracking
  • Tracking with modality or variability
  • Interaction with specifications: system-level requirement not to oversubscribe, but not on subcomponents. can say “mass must be under X” but that doesn’t work as expected
    • The difficulty: give everyone a target and they will work to that target but not past it; when some component can’t go down to target the system ends up oversubscribed
    • the example about asymmetric incentives
  • Estimation — initial and improving
  • Reserves that decrease over time

• Need: give incentives for teams to go under a target or use a shared target
  • Leadership effect
  • Marketplace mechanism?

Chapter 43: Safety and security design

• Introduction
  • what this design aspect is about
  • define safety, security, and other similar properties
  • how this weaves throughout the development phase

• Objectives
  • design and build a system that meets customer or regulatory goals for keeping things safe, secure, or similar properties
  • gather objective evidence that the system meets those goals
  • support fixing problems when they are discovered
  • support evolving the system without breaking these properties

• Key terms
  • Incident
  • Hazard
  • Accident
  • Risk

• General method
  • picture of general flow
  • define the objectives

• Safety-specific design
  • relation to safety standards

• Security-specific design
  • working out potential threat actors

Chapter 44: Design for shared resources

• Introduction
  • About designing systems that involve sharing limited resources among independent parties
  • What kinds of systems this applies to
  • Define typical objectives: fairness, overuse/sustainability
  • How this fits throughout the development process

• Objectives
  • design a system that can mediate how multiple users share limited resources
  • kinds of resources
  • fairness
  • sustainability

• Key concepts
  • incentives
  • monitoring
  • enforcement
  • rivalrous goods
  • excludable goods
  • the four combinations

• General method
  • Reuse of the same method for safety and security and other properties

• Design considerations for public goods

• Design considerations for common-pool resources

• Design considerations for club goods

Part IX: Implementation

Chapter 45: Introduction

• What the implementation phase is about
• References to the vast body of literature
• Specific techniques discussed here
• Managing technical debt, unknowns, and risk

Chapter 46: Good implementation practices

Chapter 47: Integration-first implementation

• Definition
• Purpose for managing integration risk early
• Dependencies among components and implementing in parallel or sequentially
• Examples
• Relation to plan
• Relation to methods (next)

Chapter 48: Skeletons and mockups

• Purpose of tackling integration uncertainty and risk first
• Definition
• Relation to prototypes

Chapter 49: Implementation using testing

• Purpose of using testing during implementation
• Comparison with TDD
• Tools

Part X: Verification

Chapter 50: Introduction

• purpose
• verification implementation
• verification methods
  • when to use each
• inspection and review
• inspection implementation
• analysis
• analysis implementation
• testing
• testing implementation

Chapter 51: Recording evidence

• traces from purpose to specification to design to implementation
• records of testing
  • what the test was, and what it verifies
  • linked to specification and implementation artifacts
  • testing procedure used
  • record of the execution
  • pass/fail result, and log of problems
• records of analysis
  • what it was to verify
  • methodology
  • output of analysis
  • pass/fail result, and log of problems
• historical evidence from earlier versions
  • any evidence is specific to a version of purpose, specification, and implementation (or design); invalidated after any of those change

Chapter 52: Good verification practices

Bibliography