SEVEN WORDS YOU CAN NEVER USE IN A REQUIREMENTS SPECIFICATION

Les Grove
Tektronix, Inc.
Prepared for the 2006 Telelogic Americas User Group Conference

A requirement specification is the one place where all of the stakeholders involved with a project have a vested interest. Unfortunately, requirements are often not written clearly for the people who depend on them. This [article] will help people to use precise language in writing their requirements, detect problems when reviewing requirements, and avoid misunderstandings when using requirements.

The seven bad words referenced in the title were selected from real Tektronix specifications in various forms of readiness (draft, pre-review, post-review, released). Each word is representative of a particular type of word.

The problem with this word is that it implies certainty, but can never be verified. How does one verify that “Values shall always be available”? Similar words include all, every, and never.

#6 Some

This term is just plain vague and can thus be interpreted a number of ways. When a requirement states that “There will be some restrictions on changes a user can make,” this leaves it up to the designer to either spend time talking with the author or guessing at what the restrictions should be. Similarly vague words include most, sometimes, and usually.

#5 Appropriate

This is a vague adjective that indicates that the requirement has not been thoroughly considered. An author may think that anyone would understand “Put up an appropriate message when there are no more available slots,” but this type of use could indicate something more problematic. What is the real requirement here? There needs to be an indication that there are no available slots, but the author dabbled into design by stating that the solution is some sort of message—and just didn’t want to specify the message. So, in this example, a more basic problem is uncovered by catching the vague adjective. Other adjectives to watch out for include easy, user-friendly, fast, and graceful.

#4 Handle

Vague verbs such as this do not describe what the system will actually do. It is a sign that the author has thrown up their hands in frustration because the system should do something in a given situation, but can’t decide what. When a requirement states that “The application must handle suppressed data,” the designer has nothing to base any design decisions on. Similar words include improve, provide, reject, and support.

#3 Etc.

Words like this indicate two problems. First, there is an incomplete requirement that leaves the designer to complete the list. “The user shall be notified of loss of signal, loss of clock, etc.” indicates that there are other states and conditions that the user should be notified about, but are not specified. The second problem with statements like this is that there are usually multiple requirements in the single statement that need to be separated out. Similar words are another, other, including, not limited to, and such as.

#2 It

Pronouns in requirement statements can be very clear to the author, but misleading to the readers. The statement “Touch screen operations provide audio feedback. User can turn it on or off’” does not indicate whether it refers to the touch screen or the audio feedback. Also, it indicates that there are two requirements: audio feedback and some sort of switching capability. Simply separating the two sentences in this example does not solve any problems either because the second sentence totally loses its context due to the pronoun. The word this is another pronoun to avoid.

#1 Should

At Tektronix, this word is the worst offender, as it is used more frequently than any of the other words in this list. This opinion goes against some other requirements books and the practices of some very large companies (particularly defense and finance), but Tektronix relies on DOORS attributes to indicate requirement priority. Because it implies uncertainty, testers cannot be sure there is an error if the negative occurs. When a requirement states that “The default should be auto-detection,” is it an error during testing if the default is something else? Other uncertain words are and/or, can, could, if possible, and may.