Requirements Document

1/25/12 11:33 AM

Best Practices - Requirements Document

Best Practice Title Page 1.0 Introduction 2.0 Requirements 2.1 Problem Domain 2.2 Query Requirements 2.3 Behavioral Rule Requirements 2.4 Mapping Requirements 2.5 Operations Requirements 3.0 Design Constraints 4.0 Deprecated Requirements 5.0 Glossary 6.0 Change Log Template Requirements Document Example Requirements Document

Rationale
A Requirements Document contains requirements for a software program/library, subproject or project. The document defines a problem to be solved in a Problem Domain (the domain that the software interacts with) and describes the effects a computer program, in the Software Domain, must produce to solve a problem. A requirement statement, in the Requirements Document, addresses each required effect of the program or project. Note that Requirements Documents do not generally contain interface specifications or design information. In a large project there is generally a hierarchy of Requirements Documents. A top level Requirements Document describes the project and is high level requirements. This document is usually the first development document created for a project. Since the Problem Domain is known and the HOW the software is to effect the problem domain is known, the top level Requirements Document can be written. This is frequently derived from the project. At this early stage in a project the interfaces between the software and
http://www.ittc.ku.edu/~searl/BestPractices/ReqDoc.html#Deprecated Page 1 of 6

Requirements Document

1/25/12 11:33 AM

the problem domain are not yet known and the design of the software is not yet known. Based on the top level Requirements Document an initial architecture Design Document is created. This document generally divides the project into subprojects. Each of these subprojects then has a Requirements Document written for it. The subdivision continues until a level of design is reached which can be easily implemented. During the subdivision of the project a level is reach where it is obvious from the requirements that subproject interfaces can be specified. The interfaces are specified in Specification Documents. The purpose of writing Requirements Documents is: Interface specification, design, implementation, testing and packaging, guidance Formal and effective communication, Knowledge capture. A Requirements Document is used by interface Specification Document writers, Design Document writers, implementers, testers, and packagers to ensure that they capture and carryout all of the requirements of the project. Each requirement must be satisfied by some aspect of the project. This software practice document is largely based on the book "Practical Software Requirements", by Benjamin L. Kovitz, Manning Publications Co., 1999. Please refer to this book or other books covering the content and style of requirement documents.

Best Practice
The remainder of this document contains the Best Practices for writing a Requirements Document. Follow this link to find Best Practices that are common to all project documents. Here are some important practices to keep in mind that are specific to requirements documents: Use the word 'shall' in each requirement statement. Do not use the word 'should' in a requirement statement. The word 'should' is only used for statements of desirable features (not required features). The contents of the Requirements Document must include, but is not limited to, the following sections: Title Page Introduction/Overview Requirements Design Constraints Deprecated Requirements Glossary Change Log

Title Page
http://www.ittc.ku.edu/~searl/BestPractices/ReqDoc.html#Deprecated Page 2 of 6

Requirements Document

1/25/12 11:33 AM

All project documents use the same Best Practices for the title page of the document. Follow this link to find the Title Page Best Practices.

1. Introduction/Overview
All project documents use the same Best Practices for the Introduction/Overview section of the document. Follow this link to find the Introduction Best Practices.

2.0 Requirements
Requirements are statements of what effects the program must produce in given Problem Domain conditions. In this section are not only the requirements but descriptions of the actors/entities and their attributes, events, and relationships between Problem Domain actors and relationships between the actors and the software. The Problem Domain description is placed in the 'Problem Domain' subsection. The requirements may fall into easily identifiable categories that then can be used as requirement sections in the requirements document. If this is not the case then the following sections are recommended for the requirements document. The Requirements section may include any of the following subsections but is not restricted to these subsections: 1. 2. 3. 4. Query Requirements Behavioral Rule Requirements Mapping Requirements Operation Requirements

An example of an alternate set of subsections follows: 1. User Interface 1. Graphical interface 2. Command line interface 2. Databases 3. Network Communication 4. Third Party Software Utilized If the recommended requirements subsections are use but there are requirements that do not fit into the categories of the sub sections then appropriate additional subsections must be created for the requirements. Each individual requirement must have an identifier. The identifier is of the form 'R-XXX' where XXX is a dotted number. The number shall consist of the requirement's section number the requirement is in plus a dotted number. Requirement identifiers are used in Specifications Documents and Design Documents to refer to requirements in the Requirements Document. An example of a requirement follows: R-2.1.3 The user shall be notified of invalid keystrokes with a bell sound.

http://www.ittc.ku.edu/~searl/BestPractices/ReqDoc.html#Deprecated

Page 3 of 6

Requirements Document

1/25/12 11:33 AM

After the initial release of a Requirements Document, version 1.0, requirements may NEVER be renumbered. This Best Practice exists to prevent having to change other documents that refer to requirements by number (as the must). At times it is necessary to add new requirements to a Requirements Document after the initial release, version 1.0. If there are additional requirements placed between existing requirements then the requirement id of the new requirements must have letters appended to the requirement id of the preceding requirement. Example: If a new requirement is added immediately after requirement R-2.1.3, the identifier of the new requirement is R-2.1.3a. Once an initial Requirements Document has been released, version 1.0, the text of any deleted requirements shall be replaced with the word 'Deprecated'. This prevents reuse of requirement identifiers and confusion in documents that refer to requirements. The text of deprecated requirements is moved to the deprecated section of the document for historical purposes. An existing requirement may be modified but must continue to apply to the same effect. Valid changes include but are not limited to quantities, qualities and names within the requirement.

2.1 Problem Domain

The Problem Domain subsection contains a description of the actors/entities/objects, events and relationships found in the problem domain. These characteristics of the Problem Domain are referred to in the requirements. No requirements are placed in the Problem Domain subsection. The entities/objects may include people, computers, vehicles, mechanical equipment, electronic equipment, inventory items, information, etc. Entities and objects interact directly with the software or have an internal representation in the software. Any attributes of the entities/objects that must be known by the software must be described. Note that the details of any internal software representation of entities and objects are not described (that would be either interface Specification Document or Design Document information). The actions that entities can perform must be described. These actions may influence other entities/objects or the software. Only those actions that are referred to in the requirements are relevant. The relationships between entities/objects must be described. Only those relationships referred to in the requirements are relevant. In nearly all Requirements documents it is necessary to include a diagram showing the actors in the Problem Domain and their relationships between each other and the software.

2.2 Query Requirements

These requirements address information queries from an actor in the Problem Domain. Not only would there be requirements concerning the contents of the query but also where the software obtains the information initially and what it information it stores. A query is a request for information from the software by a Problem Domain actor or information generated in response to an event from the Problem Domain. Requirements in this subsection include the following:
http://www.ittc.ku.edu/~searl/BestPractices/ReqDoc.html#Deprecated Page 4 of 6

Requirements Document

1/25/12 11:33 AM

Description of queries from Problem Domain to respond to or data to generate for the Problem Domain when an even occurs. Descriptions of attributes of objects/entities in the Problem Domain that the software must have internal representations of. The attributes of these entities are returned in queries. Relationships between objects/entities known by the software and used in responding to a query. Description of events that change known objects/entities, attributes of objects/entities and relationships. Descriptions of method of accessing information from the Problem Domain or sending information to the Problem Domain. Descriptions of external file formats to ad-hear to. These may references to other documents. File formats that are used only by the software are described in interface Specification Documents. Restrictions on information transfers between domains are described. The restrictions would include items like data rate, time delay, protocols, etc. Examples of requirements in this section are: network interfaces, database interfaces, signals, interrupts, etc.

2.3 Behavioral Rule Requirements

These requirements address control problems with the focus on causation. The actions the software takes to make the actors in the Problem Domain follow specified rules. Requirements in this subsection include the following: Behavior rules of the problem domain used by the software to control the problem domain. Actions on the problem domain that the software can initiate. An example of the requirements in this section is: When timer A expires the software forces networked computer B to perform action C.

2.4 Mapping Requirements

These requirements address data transformation problems. The software generates output data that it transforms from input data. Requirements in this subsection include the following: Mapping between input and output sets. Example: The video input stream is processed to recognize a human face. The name that matches the face is send to the login process.

2.5 Operations On Software Requirements

These requirements address work-piece problems. Typically these are user interfaces requirements. Requirements in this subsection include the following: Operations that can be performed on the software (typically through a user interface).
http://www.ittc.ku.edu/~searl/BestPractices/ReqDoc.html#Deprecated Page 5 of 6

Requirements Document

1/25/12 11:33 AM

Example: A Dialog window is provided to alter the attributes of a widget.

3.0 Design Constraints

This section contains constraints placed on the software design that should be placed in the Design Document but are known before the project is begun. This section might refer to a Software Best Practices Coding Style document. Constrains such as hardware platform, operating system and source language can be placed here.

4.0 Deprecated Requirements

Requirements that are removed from the Requirements section after the initial release are moved to this section. This provides a history of changes to the document and also allows the maintainer of the Specifications Document and Design Document to track the disposition of requirements referred to in these documents.

5 Glossary
All project documents use the same Best Practices for the Glossary section of the document. Follow this link to find the Glossary Best Practices.

6 Change Log
All project documents use the same Best Practices for the Change Log section of the document. Follow this link to find the Change Log Best Practices. Leon S. Searl Last Modified: 2001-01-17

http://www.ittc.ku.edu/~searl/BestPractices/ReqDoc.html#Deprecated

Page 6 of 6