Requirement Summaries

Problem

I want to make the specification understandable / readable to business sponsors who do not need to review all of the detail.

Solution

Provide separate requirement summaries, written in a less formal prose style. Communicate the sense or gist of one or more connected series of requirement statements. Use different text formatting to highlight the summaries to casual readers, and to distinguish them from formal requirements.

Requirement summary text does not have to meet your requirement Rules (e.g. testable, clear, identified ambiguity), but should effectively summarise the scope.

Example

requirement-summary-example.png

Discussion

Requirement statements written following the rules and style guidelines described elsewhere in this Cookbook can sacrifice superficial readability for the more casual reader. Separate Summary statements can be written specifically to provide a readable overview of one or more formal requirements.

It must be clear to other readers that the Summaries are not to be construed as requirements, tests written for them etc. Similarly, for requirement authors, writing brief Summary text should not be substitute for more formalised clear, concise, atomic statements.

A useful technique when approaching writing a block of requirements is to write the Summary statements first, with requirement labels. This helps the author initially focus on describing the general scope of the requirements without filling in the details. This also allows an early-stage review to be held, for the purpose of verifying the scope completeness of the summarised requirements.

Note that ambiguous terms such as “basic details” in the Summary text are acceptable, in order to make the summary more readable and immediately meaningful. However, it would be expected that the actual requirement statement formally defines the scope of user action being described (or refers to a definition somewhere else in the document) … such as the use of the formally defined phrase “minimum capture data” in the above example.

Unless otherwise stated, the content of this page is licensed under Creative Commons Attribution-ShareAlike 3.0 License