Requirements Management Using Tables

areful management of requirements is generally accepted as a necessary prerequisite for project success and production of quality code. All projects, big or small, can benefit from the attention paid to requirements.

However for many projects, requirements efforts are practically nonexistent. The requirements are provided verbally and not documented at all. Even on small projects, this approach often leads to mistakes and products that just don’t do the job. There is no effective way for the customers, designers, and testers to compare notes and ensure that they are all working towards the same goals.

At the other extreme, requirements efforts can produce formal, military-style specifications. These efforts are almost always quite expensive. But despite the expense, the resulting specifications often prove to be only marginally useful. Often the actual requirements are buried in a huge document and hidden behind reams of boiler plate.

This article describes techniques for maintaining requirements in a tabular form that:

• Provides a concise representation
• Can be used to support all phases of the project
• Is cost-effective for small, informal projects
• Can be scaled up to meet the needs of large, formal projects

The analysis team uses the table to record the requirements and information about how they were derived. Each requirement is given an identification code or number that provides a unique and quick way to reference the requirement. The text of each requirement is included in the table so that it can be used as a stand-alone requirements document. Lastly, a reference to the source of the requirement helps designers and reviewers understand the requirement.

The design team uses the table as its primary source of information for working out the design. By allocating each requirement to specific design elements, the team makes sure that all requirements have been addressed.

The test team uses the table to plan and record completion of verification activities. To accomplish this goal, a method for verifying each requirement is included in the table. Common methods for verifying a requirement include inspection, analysis, demonstration, and test. A short statement that explains the basic verification concept is composed, to help ensure that the entry is properly thought out.

A verification level is also specified for each requirement. Common levels are unit test, integration, and acceptance test.

Once the requirement has been verified, its status is recorded in the table. Providing a reference to support documentation, such as reports or test results, is a useful technique.

Entering requirements information into the table
Requirements are statements that describe the mandatory characteristics of a product. They provide the means for the customer to convey to the designers what is expected. Characteristics of the product that the customer is willing to leave up to the designers would not be stated as requirements.

Customers buy products that fill certain needs. Often they are indifferent to the fact that the product consists of a combination of hardware and software. What is important is the performance of the complete device. With embedded software, a product is being developed that just happens to have some of its functionality provided by the software. Ultimately, the product will be sold, not the embedded software.

This naturally and properly leads to specifications that provide only the requirements for the final product. Usually, little or nothing is said about the embedded software in a product specification. Incorporation of embedded software in a device is really a design decision of the product designers.

However, the software designers need to understand what is expected of them. Typically, this information must be gleaned from a variety of sources, as shown in Figure 1, which includes:

• The contract
• Product specifications
• Algorithms descriptions
• Hardware designs
• Test and factory support needs

• Organize the requirements in a sensible fashion. Usually this is done by grouping the requirements as they apply to specific capabilities. The capabilities are identified by generating a model of the software. For object-oriented designs this could be a class model of the problem domain, where each object would correspond to a capability; structured designs could use a high-level process (Data Flow) model, in which each process would correspond to a capability
• Record the source of the requirement. The source might be a reference to another document or a summary of the rationale that explains why the requirement was levied
• Examine the table to ensure that it includes the information that the software designers need. Generally, they require information about states and modes, algorithms, parameters, and interfaces
• Examine each requirement to make sure it is of good quality. Each requirement should be verifiable, necessary, attainable, and clear. It should express what is needed, not how it is to be done. And each requirement should apply specifically to the software, not to the hardware or overall product

As the design is formulated, the designers update the table to show how the requirements are allocated to software modules. When a requirement cannot be allocated to specific modules, a statement of how the requirement has been satisfied can be included in the table. The designers should then scan the table and note any requirements that have not been addressed.

Entering verification information into the table
Ultimately, the quality of the software will be proven by the successful operation of the final product. However, modern quality theory emphasizes complete self-inspection at each stage of work. The idea is to prevent a bad product from being passed down the production line. For software, that “line” can consist of:

• Analysis: define the requirements
• Design: devise a means to satisfy the requirements
• Code: implement the design
• Unit test: a stand-alone test of each software module
• Integration: test the units together with the hardware
• Acceptance test: final acceptance of the software

The requirements table is used to capture the verification plan and to record the verification status for each requirement as the software passes down the line. When all of the requirements have been met and verified, the software is ready for delivery.

One technique for generating the verification plan is to work backwards from the delivery as follows.

Define an acceptance test that confirms the overall operation of the software. Depending on the project environment, this test might also be referred to as the qualification or regression test.

The acceptance test can be defined by marking paths through a State Transition Diagram that describes the major modes of the product, as illustrated in Figure 2. The paths should visit every state on the chart, and should be selected to use transition criteria that can be forced with available test equipment. (Activating every possible transition isn’t necessary, nor is it practical.)

Define some criteria to verify the functionality of the product in each state. For example, the outputs of a servo control system might be compared to simulation results.

After the test is defined, go through the table and mark the requirements which are verified by the acceptance test.

Next, examine the table to determine which remaining requirements should be tested at the integration level. Good candidates for this category are requirements that involve multiple units or can only be tested with special hardware setups.

Finally, review the table once again and mark the remaining requirements as being verified at the unit level via test or inspection. You should consider any of the remaining requirements that turn out to be unsuitable for unit test for inclusion in the integration or acceptance tests.

Improved communication
Traditional methods seem to encourage, or perhaps require, each team to generate their own separate versions of the requirements tables.

On many projects, the design team may go through a specification and extract the shall statements to create a requirements table. The table becomes the primary requirements tool used by the designers. Similarly, the test team goes through the specification to create their own tables so they can do their test planning.

Usually, shortcuts are taken. For instance, many teams commonly list only the requirement identifiers, instead of the requirements text. This makes effective review of the material practically impossible because so few people are willing to wade through a sea of numbers. Only the person who creates the table will have any real understanding of what was done. I’ve found that communication and the review process are much improved when analysts, designers, and testers all work from a common table.

Lower documentation costs
Military-style documentation requires the use of various tables in requirements, design, and test documents. On recent projects we have succeeded in convincing our customers to allow us to attach the common table, which satisfies the intent of the various documents. This practice has reduced documentation cost and errors by eliminating the need to convert the requirements among various forms of representations.

Projects that lack documentation requirements can just use the tables as the documentation. And because the tables provide positive benefits for modest cost, they are useful for even small projects that might otherwise go undocumented.

Tool support
Users of CASE tools will be familiar with the traditional concept of entering requirements statements as attachments to drawing nodes (creating a p-spec for a bottom-level process in a Data Flow Diagram, for example). When you choose to take this approach, you must extract the requirements and represent them in alternate formats for review, design, test, and documentation.

Many CASE tool vendors have worked hard to provide tools to extract the requirements and produce documents. Unfortunately, while some large projects can claim some success, the actual process has proven too difficult and expensive for most projects. I know of no project in which the results seemed worth the expense, and of no case in which the tools and lessons learned on one project proved to be helpful for another.

I believe this general lack of success stems from a flaw in the basic concept. The technique puts the requirements in place where they are not directly usable and thus forces additional processing. CASE tool vendors would do better by capturing the requirements in a tabular form that supports links to the drawing nodes.

In direct contrast to the CASE tools, spreadsheet programs provide a direct table format and have proven to be reasonably cost-effective requirements-management tools. Because nearly everyone understands spreadsheets, it is easy for users to enter, update, and sort the requirements information.

Sometimes large programs need additional management features, such as change control and automatic tracing. In recent years, several table-based commercial tools such as DOORS and Vital Link have become available that provide these additional features.

Sophisticated simplicity
When presenting a simple technique, I worry that it will be dismissed as trivial. However, you shouldn’t confuse simplicity with a lack of sophistication. Finding a good notation has often been a key to progress. The tabular representation I’ve described in this article has proven to be a cost-effective technique for managing requirements. It provides the requirements in a concise format, avoids unnecessary costs, and helps coordinate development activities.

I also worry that a simple technique like this one will be heralded as a silver-bullet solution to multiple problems. Experience has shown that representing requirements in tabular form will indeed provide positive benefits to a project. However, managing requirements remains hard work that requires skilled personnel and costs money. The key to improvement, as always, is to find techniques that return good results for the effort you expend. esp

Bob Petty received his BS degree in Physics from Idaho State. He has worked as an engineer developing logic, microprocessor, and software designs. He is currently a senior engineer for Hughes Missile Systems Co., where he designs software embedded in new missile systems. In his spare time, he teaches classes on software development and writes Macintosh and Windows applications. He can be reached at bobpetty@aol.com.

Table 1: An example requirements table
ID	Requirement	Source	Allocation	Qual Method	Qual Level	Status
1	The software shall implement the modes of operation shown in Figure 1.	System Spec 3.1.2.6	Mode Control	Test	Acceptance
2	The software throughput margins shall be no less than 50%.	Contract 3.2.2.5	This is actually a system design issue assigned to the software by contract.	Test & RMA	Integration
3	The software shall be written in Ada.	Contract 3.2.2.4	All	Inspect	Unit	Pass 10/12/97 See SDF

Return to Embedded.com

Send comments to: Webmaster
All material on this site Copyright © 2000
CMP Media Inc. All rights reserved.