Writing Useful Requirement Specifications

Type: Rules
Sources: Planguage Glossary, own experience


This article explains why it is a good idea to specify requirements (or designs) giving commentary or background information.


  • implementable specification DEFINED AS written specification that translates into real implemented systems.
  • background specification DEFINED AS the part of a specification, which is useful related information, but is not central (core) to the implementation, nor is it commentary. Examples include version, author, ambition, gist.
  • commentary specification DEFINES AS remarks about other specifications. Examples include sources, credibility, and traceability information.

Note that the above definitions use the word 'specification' in a wide sense. Sometimes 'specification', or 'spec' is used to mean a whole (requirements) document only. Here it includes single requirements or any set of requirements, too. It also includes not only requirements, but also designs and plans.

Rules and Notes

R1: If you have any useful background or commentary information about an implementable specification, always add it to the specification.

  1. Specifications are means to transport ideas over a long distance, either in time from one head to another, or both. Anything that adds to the understanding of the implementable specification then, or there, is useful.
  2. Specifications are means to find, understand and analyze risks, for example the risk of a given design concerning the set of requirements. Anything that adds to this is useful.
  3. Background and commentary information answers - at least in part - the critical "WHY" question: Why do I specify this?
  4. Specifications of requirements might include statements about acceptance criteria (a form of implementable specification). While acceptance criteria should be written unambiguously and clearly without the need to consult the respective requirement, anything that adds to their understandability is useful and thus should be added (to the acceptance criteria or the requirements, or both).//
  5. Obviously there is a trade-off. If the specification becomes unreadable because of extensive background or commentary text, you should think about what is really useful and what is not. Do a readership analysis.

R2: Clearly mark background or commentary text as such.

  1. Only clearly marked text is unambiguously distinguishable from the implementable specification.
  2. This can be done in various ways, including tags like "comment", "assumptions" etc. within what you would call a single requirement, or markup-conventions like text in italics, or special sections within the requirements specification document.

Costs, Savings

You might wonder how much useful background or commentary information one can find for a single 'requirement'. Finding and writing this information can be time consuming. However, it is worth the effort. It is the author's responsibility to make sure the readership easily comprehends what he has written; write once, read many.

We can estimate the savings by measuring (and assuming a money value for defect removal cost) the number of defects found while inspecting specifications against the following (or similar) rule: "Each uniquely identifiable specification shall include at least the following non-implementable information: source, credibility, assumptions, benchmarks." Cost can be estimated by observing specification writers and taking the time they need for the respective parts of their specification.

Side effects

  • You as an author will start thinking about the specification more deeply.
  • You will start to consider things like the credibility of information, and use it for decision making. ('Is that so?')
  • You will more likely write more real requirements, and less designs-disguised-requirements.
  • You will have to argue as to why include all this 'stuff' in an 'otherwise lean' document. (Link to this article…)
  • You will have to explain why it takes you, say, 60 mins to write, say, 2 requirements. (Link to this article…)


"A stitch in time saves nine."

Related Pages

rating: 0+x

If you want to know more about a topic, simply tag the article with a 'morePlease' or 'examplesPlease' tag!


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