How do you know what a system is supposed to do and what it is not supposed to do? Requirements are intended to create an easily validated, maintainable and verifiable document describing a system’s planned functionality.
What is lacking in today’s requirements? Requirements are typically described in natural language because both the customer and vendor must understand them. However, many words and phrases have meanings that can be interpreted based on the context in which they are used. Requirements described in this form can have several severe problems including: ambiguity, inaccuracy and inconsistency.
The criticality of correct, complete, testable requirements is a fundamental tenet of software engineering. The success of a project, both functionally and financially, is directly affected by the quality of the requirements. [Doing Requirements Right the First Time!, Theodore F. Hammer, Linda H. Rosenberg, et al., 1998]
Who Needs Requirements?
The communication of requirements is the most critical, difficult, and error-prone task in IT projects. Research has shown that projects that proceed to the coding phase with missing or incorrect requirements are almost certain to fail. [A Systematic Approach for More Effective Communication of Functional Requirements and Specifications, Bill Walton]
Consider the various stakeholders or audiences for the requirements – on which each is dependent for their own role in the project lifecycle:
- Customer – Statement of work for vendor, acceptance criteria
- Marketing – Documented product capabilities
- Project Management – Estimates, project plans, project goals, risk planning
- Development – Design and coding of the system
- Testing – Verification of the system
- Technical Writing – User manuals and tutorials
Unless there is effective communication of information the same words can mean different things to each party, or different words can appear to repeat the same thing, becoming a source of misunderstanding and therefore error.
Quality Requirements
Customer dissatisfaction often surfaces at the acceptance phase as discrepancies appear between what was built and what the customer thought was being built – a clear result of lack of quality requirements.
Some of the commonly recognized crucial attributes of quality requirements are:
- Completeness
- Consistency
- Correctness
- Understandability
- Unambiguousness
These quality attributes tend to be considered subjectively. However, some of these quality attributes can be linked to indicators to provide evidence that the attribute is present or not. The NASA Goddard Space Flight Center’s (GSFC) Software Assurance Technology Center (SATC) defines categories of quality indicators related to individual specification statements as: Imperatives, Continuances, Weak Phrases, Directives, and Options.
The SATC’s studies give the following specific words and phrases to be indicators of a document’s quality as a specification of requirements:
- Imperatives – Words and phases that command that something must be done or provided. The number of imperatives is used as a base requirements count. Eg: Shall, must or must not, is required to, are applicable, responsible for, will, should
- Continuances – Phrases that follow an imperative and introduce the specification of requirements at a lower level, for a supplemental requirement count. Eg: As follows, below, following, in particular, listed, support
- Directives – References provided to figures, tables, or notes.
- Weak Phrases – Clauses that are apt to cause uncertainty and leave room for multiple interpretations measure of ambiguity. Eg: Adequate, as applicable, as appropriate, as a minimum, be able to, but not limited to, be capable of, effective, easy, effective, if effective, if practical, not limited to, normal, timely
- Incomplete – Statements within the document that have TBD (To be Determined) or TBS (To Be Supplied).
- Options – Words that seem to give the developer latitude in satisfying the specifications but can be ambiguous. Eg: Can, may, optionally
The SATC developed the Automated Requirements Measurement (ARM) tool which project managers can use to assess the quality of their requirements documents easily and on an on-going basis during the life of the documents. The ARM tool searches the requirements document for terms the SATC has identified as quality indicators.
Requirements Style Guide
Similar to a development coding standard, a requirements style guide outlining when and where such terms and structures must and alternately may be used can help maintain control over ambiguity, consistency, and completeness.
However, although many organizations have published documentation standards that include standards for specifying requirements, none are universally accepted. The standards that are imposed seldom go beyond providing an outline or template of the general information to be provided. In many cases no style guidelines are established. As a consequence, requirements documents from various sources tend to bear little resemblance to one another. [Automated Quality Analysis Of Natural Language Requirement Specifications, William M. Wilson, Linda H. Rosenberg, Lawrence E. Hyatt]
The ultimate symptom of vague requirements is that developers have to ask the author, analyst or customers many questions, or they have to guess about what is really intended. The extent of this guessing game might not be recognized until the project is far along and implementation has diverged from what is really required. At this point, expensive rework may be needed to bring things back into alignment. [Karl Wiegers Describes Ten Requirements Traps to Avoid, Karl Wiegers, 2000]
Karl goes on to suggest that requirements authors avoid using subjective and ambiguous words like minimize, maximize, optimize, rapid, user-friendly, easy, simple, often, normal, usual, large, intuitive, robust, state-of-the-art, improved, efficient, flexible, “and/or” and “etc.”. Indicate current uncertainties or areas to further clarify with “TBD” markers to make sure they get resolved before design and coding proceeds.
Summary
Quality documentation is complete, clear and concise. These used to be considered intangible concepts, difficult to measure. With a well defined style guide that addresses the quality attributes like those identified by SATC, metrics can be rapidly developed and analyzed to reveal the strengths and weaknesses of the requirements documentation.
Most projects come with that sense of urgency attached – we need to start coding and we need to start now. In this kind of rushed atmosphere, it’s hard to convince yourself to take the time to even perform documentation activities at all, let alone to develop and apply a new documentation technique.
So why should you go to the trouble? Because addressing the aspects of quality (or lack thereof) on a project leads to working smarter rather than harder, better products, more satisfied customers, and higher profits. But the perfect and easy time for doing the things you know you should do will never come.
Remember, industry data suggests that approximately 50 percent of product defects originate in the requirements. Perhaps 80 percent of the rework effort on a development project can be traced to requirements defects. Anything you can do to prevent requirements errors from propagating downstream will save you time and money. [Inspecting Requirements, Karl Wiegers, 2001]
Read “A Methodology for Writing High Quality Requirement Specifications and for Evaluating Existing Ones” by Linda Rosenberg for more information on the NASA SATC quality attributes (slides 37-68) and a description of the free ARM tool (slides 125-133, no longer available for download).
