Requirements Specification

Definition

Requirements Specification

the requirements engineering task during which the analyzed requirements for a system, application, application domain, or component are published in requirements specifications (and related requirements documents)

Classification

As illustrated in the preceding figure, Requirements Specification is part of the following inheritance hierarchy:

• Type: Abstract
• Superclass: Engineering Task
• Subclasses: None

Responsibilities

The typical responsibilities of Requirements Specification are to author, generate, and publish approved or updated requirements in the following:

• The requirements specifications:
  • Requirements Executive Summary.
  • System Requirements Specification.
  • External API Specification.
• All related requirements documents:
  • Application Vision Statement.
  • Glossary.
  • Domain Model Document.

Preconditions

The requirements specification task can typically begin when the following preconditions hold:

• The initiation phase has started.
• The requirements team is staffed and adequately trained in requirements specification techniques.
• Some requirements to be specified have been either analyzed (e.g., functional requirements) or else can be reused as is.

Completion Criteria

The requirements specification task is typically complete when the following postconditions hold:

• All requirements have been specified in the appropriate requirements specifications.
• All related documents (e.g., Glossary, Domain Object Model) have been produced.
• All deliverable requirements work documents have been approved, baselined, and accepted by the customer representative(s).

Steps

The requirements specification task typically involves the requirements team performing the following steps in an iterative, incremental, parallel, and time-boxed manner for each specification or related requirements document:

• Locate, obtain, and read the appropriate conventions:
  • Content and Format Standard.
  • Inspection Checklist.
  • Documentation Template.
• Use the template to create a blank specification or document.
• Fill in the front matter.
• Fill in the introduction section.
• Either manually or automatically enter the major content (e.g., analyzed and reused requirements) into the appropriate sections.
• Fill in the appendices including all major issues, TBDs, and assumptions.
• Generate the associated tables of contents and tables of figures.
• Informally evaluate these documents against their:
  • Content and format standards.
  • Inspection checklists.
• Iterate the specifications and related documents as necessary.
• Notify the requirements inspection team that [cohesive parts of] are ready for inspection.
• Maintain the specification or document.

Techniques

The requirements specification task can typically be performed using the following techniques:

• Content and Format Standards
• Documentation Templates
• Inspection Checklists
• Standard languages such as XML, HTML, or MS Word
• Cross Functional Teams.
  Requirements specification should be performed by a cross-functional requirements team including multiple roles.
• Incremental development.
  Incrementally specify the requirements.
• Iteration.
  Iterate the requirements specifications.
• Parallel Development.
  Specify the requirements in parallel with:
  • Other requirements engineering tasks (e.g., requirements elicitation, requirements reuse, requirements analysis, requirements management).
  • Other activities (e.g., architecting, design, testing, management, configuration management, training).
• Timeboxing.
  Timebox the requirements specification task so that new increments of potential requirements are available for driving the architecting, design, implementation, and testing activities at regular intervals.

Work Products

The requirements specification task typically results in the production of all or part of the following work products:

• Application Vision Statement, which documents the customer organization's vision of a single application.
• Requirements Executive Summary, which is used to formally summarize the requirements for the customer.
• System Requirements Specification, which is used to formally specify the functional requirements, data requirements, quality requirements, and constraints.
• External API Specification, which is used to formally specify any external application programmer interfaces.
• Glossary, which is used to formally define the abbreviations, accronyms, and terms used on an endeavor.
• Domain Model Document, which uses an object model to formally document the relationships between application domain concepts defined in the project glossary and requirements specifications.

Guidelines

• Each individual requirement should be:
  • Mandatory (i.e., must be fulfilled as opposed to a “nice to have” item on some wish list).
  • Correct.
  • Cohesive.
  • Consistent with other requirements and higher-level goals.
  • Unambiguous.
  • Not redundant with other requirements.
  • Feasible (i.e., implementable given the constraints of technology, cost, schedule, etc).
  • Externally observable when treating the application or component as a black-box.
  • Validatable (e.g., testable), as certified by the independent test team or user experience team (for usability requirements).
    This may require the additional specification of associated validation criteria (i.e., criteria that can be used to determine whether or not the requirement has been correctly implemented).
  • Uniquely identified to support traceability.
  • Traced to its source (e.g., goal, document, or person).
  • Specified as a complete, concise, [functionally] cohesive, grammatically correct English sentence.
  • An accurate elaboration of an informal goal (e.g., as documented in a vision statement).
  • Scheduled for implementation by a specific milestone or release.
  • Prioritized for the milestone or release by which it should be implemented:
    • Critical.
    • Important.
    • Desirable.
    • Nice to have.
  • Managed (e.g., stored in a requirements management database or tool).
  • Controlled (e.g., placed under configuration control at appropriate time and state).
• Each requirements specification should be:
  • Correct (i.e., containing only correct information including requirements).
  • Complete (i.e., containing all required sections, paragraphs, and requirements).
  • Cohesive (i.e., containing only information that is related to its purpose).
  • Consistent (both internally and externally with other specifications).
  • Extensible (as new requirements are identified).
  • Logically Organized (so that its contents can be easily located).
  • Maintainable (as requirements change).
  • Minimal (i.e., containing no redundant or unnecessary information).
  • Relatively Stable (by the start of the construction phase).
  • Understandable (by members of its intended audiences).
• Requirements can be specified as traditional paper documents or electronically.
• Requirements can be specified in the form of traditional paper formats (e.g., MS Word or Adobe Acrobat PDF documents), spreadsheets (e.g., MS Excell), database reports, or output screens from a requirements management tool.
• Publication of requirements documents can be performed on demand or performed automatically and incrementally (e.g., via some kind of publish and subscribe mechanism).
• Because of the large size of complete requirements specifications, they are almost always specified, inspected, and basedlined incrementally, a section or cohesive set of requirements at a time.
• All types of requirements should be addressed. Too often, all of the requirements engineering training and effort go into the functional requirements, leaving the other requirements underanalyzed and underspecified.
• Care should be taken to properly document the prioritization of the requirements because it is often difficult for developers to differentiate between critical requirements that must be implemented during the current version from nice-to-have requirements to be eventually implemented given adequate schedule and staffing.
• If the analyzed requirements are stored in a requirements management tool or a modeling tool, the requirements specifications can be automatically generated from the requirements repository using appropriate templates.
• Whereas all members of the requirements team are authorized to make changes in any of the requirements work products, it is typically more cost-effective to have the majority of the initial specification work done by a technical writer trained in requirements specification.
• Although the requirements team is the owner of the glossary, the entire endeavor staff provides input and may iterate and add to the document.