Requirements

Requirements artifacts are the documents that are created, managed, and published by business analysts or product management to define the scope and content of the development project.

Requirements must be captured and tracked in a version control system just like any other class of project artifact. In addition, specific requirements must be labeled in a way that allows items to be tracked through the entire life cycle: specifications, implementation, test, release, and support.

The granularity or specificity of the labels employed depends on the rigor of the project. A product with very high quality standards, such as a medical application, will have very detailed requirements that can be tracked in precise detail.

Requirements are often sketched out in natural language and carry informal instruction to the design specification team. A very effective way to organize functional requirements is to use the concepts of User Roles and Scenarios to develop Use cases. This process creates a formal model of the system. The model can then be analyzed to create formals specification of the components of the system.

An advantage of this approach is that formal requirements and specifications can be created as relatively small modules that can be worked on separately. This allows development and test of the modules or components of the system to proceed in parallel and supports the use of an Agile development process.

Specifications to Customer Documentation

Design Specifications are an important base of information for user or customer documentation.

Specifications to Test Plans

Functional requirements and engineering specifications are the sources for the structure and content of test plans.

Specifications may include specific provision for tests. For example, instrumentation may be part of the implementation. Components may include functions that are designed to be tested independently of other components and outside of the overall system.

Specifications to Implementation

Engineering specifications define the proposed implementation at an appropriate level of detail.

The intermediate artifacts between the design specification and the implementation are the project plan and task breakdown.

Specifications are often organized as a hierarchy, with general architectural plans as the more general type and implementation guidelines or standards as the more specific types.

Specifications will define the artifacts to build and the relationships between the implementation artifacts.

Specifications are written in a mix of natural and technical language.

Backlog

Some of the artifacts in each class will represent approved, agreed-upon, active, or completed tasks.

Others will represent proposed tasks, work approved but not scheduled, etc. These artifacts comprise the backlog. A backlog is a natural and healthy part of the development process as long as it is managed correctly. One of the themes of this discussion will be to indicate when and how to address items in the backlog.

Here are some of the categories of the backlog.

Requirements that are published but not represented in specifications and/or test plans are in the design backlog.

Specifications that are not implemented are in the engineering backlog.

Implementation artifacts that have not been tested are in the test backlog.

Test plans and automation that have not been executed are also in the test backlog.

Test results that have not been reviewed are in the results backlog.

Customer reports that have not been triaged are in the support backlog.

Customer reports that have been triaged as defects but have not been fixed are in the engineering backlog.

Defects that have been fixed but where the fixes have not been delivered to customers are in the release backlog.

These are the most important components of the backlog.

Requirements to Specifications

Requirements artifacts, when published, form the basis for specifications.

Specifications must conform to requirements and may add features.

When requirements and specifications do not agree, negotiations between product management and engineering are required. The results of these negotiations may be captured in Change Request artifacts.

Ownership (or assignment) of responsibility for evaluating the state or quality of agreement between requirements and specifications belongs to both product management and engineering.

Project management responsibilities include the continual measurement of the level of this agreement. Periodic review of the published artifacts is necessary. Specifically, product management must review specifications and engineering must review requirements.

Overview

This document will define the scope of our discussion of SDLC.

We begin with the definition of the six primary classes of project artifacts.

1. Requirements
2. Specifications
3. Implementation
4. Test Plans and Automation
5. Test Results
6. Customer Reports

Requirements are documents that describe the initial or general goals of the software to be produced. These are written in a natural language (English in this case) by product management or a business process analyst. Requirements are typically based on intangibles like imagination and insight and form the primary reference documents for a project. These documents are used in turn by the engineering and documentation functions as the basis for more artifacts.

Specifications are engineering documents that describe architecture, design and development plans. These are written in a natural language by engineering management. They are based on requirements documents but include much more detail.

Implementation is produced by the engineering team from specifications and is typically in a language that can be interpreted and executed by a computer. Implementation artifacts are the tangible assets produced by the development process. Some of these assets are transferred from the development group to the customers in the form of a product or system.

Test Plans are produced by test engineering and serve as a framework for evaluation of the implementation. Test plans are based on both requirements and specifications, but not on the implementation.

Test Results are produced by test execution. Results are often in both natural language and machine-readable form.

Customer Reports are natural language documents created ad hoc as a result of the use of the implementation.

Backlog is orthogonal to the other six. It is a measure of the portion of the available artifacts (of any type) that has not yet been used to generate work or other results.

Many other useful terms will be defined in the discussion to follow. The six artifact classes stand out because they are well-understood and can be clearly defined. Most project documents belong in one of these classes.

Each of these artifact classes has a relationship to every other artifact class. Every one of these relationships will be explored at some point in the documents to follow.