One of the most difficult challenge we face in the requirements process is making the requirements detailed enough to be well understood without overconstraining the system and predefining a whole host of things that may be better off left to others downstream in the process. ("Do we really have to specify Pantone 287 as the background color in our GUI spec? No? How do you like the color they came up with last time?")
Time after time, our students pose the following question, which represents one of their biggest concerns: "To what level of specificity must I state the requirements in order to avoid any chance of being misunderstood?" Although many students are hoping for a simple answer, unfortunately, there isn't one. As if we were consultants about to sell the customer more services, the only answer we can truthfully provide is, "It just depends." For example, as an exercise in requirements writing, we often use the "light box" exercise shown in Figure 26-1.
The goal of the exercise is to write clear and simple requirements, using natural language or the use-case technique to describe the behavior of this device. In the exercise, the user is available for interview, so that the requirements writer can refine the specification with clear user input. As an example of a reasonably good effort in the natural language style, let's look at the following requirements specification (Davis 1993).
After On pushed but before Off pushed, system is termed "powered on."
After Off pushed but before On pushed, system is termed "powered off," and no lights shall be lit.
Since most recent On press, if Count has been pressed an odd number of times, Odd shall be lit.
Since most recent On press, if Count has been pressed an even number of times, Even shall be lit.
If either light burns out, the other light shall flash every 1 second.
This specification is fairly tight and would be quite adequate for most purposes. More important, it reflects the way the device user intended that it work!
However, a programmer who has the task of writing a program to simulate this behavior will discover at least one ambiguity in this exercise almost immediately: What does it mean to flash the bulb every 1 second? Still seem obvious? Let's take a look at the duty cycles in Figure 26-2.
If you were the programmer, would you pick duty cycle A or duty cycle B? Although most pick duty cycle B, it becomes clear that the requirement is ambiguous. Now, a requirements-sensitized programmer will recognize this ambiguity and will attempt to resolve it by asking the customer, "Which duty cycle should I use?" But if the programmer is not so savvy or does not recognize the ambiguity or thinks, "I know what you meant because I know how this thing should work," the behavior of the device when delivered may deviate perceptibly from the customer's stated requirements. Your project may be at risk.
In most potential applications, it probably doesn't matter whether the bulb flashes on for 1 second or 0.25 second. But if this were an electrosurgical device, it would matter a lot. The power delivered to the electrode would be 100 percent higher in duty cycle B than in A, with perhaps unfortunate results.
So, the answer to "What level of specificity must I provide?" is: "It depends on the context of your application and how capable those doing the implementation are of making the right decisions or of at least being certain to ask questions where there is ambiguity."
In the case of the even and odd counting device, the specification as stated is probably adequate. In the case of the electrosurgical device, more investment in describing the requirement would be needed. A timing diagram would be needed, and the spec would probably also have to define such issues as the rise time on the upslope of the "on" current, the precision with which the "on" time must be controlled (±x msec), and other factors; otherwise, the power delivered will not be right, and the device will operate incorrectly. Figure 26-3 summarizes this dilemma.
The goal is to find the "sweet spot," or the balance point wherein the investment in requirements provides "just the right amount" of specificity and leaves just the "right amount of ambiguity" for others to resolve further downstream.
As you move to the left from the sweet spot on the curve in Figure 26-3, you lower both ambiguity and understandability. For example, if we provided timing diagrams to an unsophisticated user, complete with timing tolerances indicated and if we maintained that level of specificity throughout, the user may well not be able to understand the spec at all or might even be unwilling to take the time to read it. Worse, due to your apparent thoroughness, the user might trust you too much and not take the time for a careful review. You are also at the risk of the customer's being unable to see the forest for the trees ("I didn't want a light bulb; I wanted you to turn on the emergency light at the end of the production line").
As you move to the right of the sweet spot, ambiguity goes up, but understandability again goes down. For example, at the extreme limit, you might simply say, "Build me an even/odd counting device," and no one could possibly understand what you mean.
Finding the sweet spot is a learned skill. It will depend on the abilities of the team members, the context of the application, and the level of surety that you must provide so that your system "works as intended."
Let's have a little fun with the issue of ambiguity and also see whether we can find some more tips that will help us "disambiguate" whenever and wherever it's necessary to do so. (If you are a fairly formal sort, without much use for the "softer" side of this problem space, you may wish to move directly to Chapter 28, Technical Methods.)
For the rest of us, let's have a little fun, courtesy of Gause and Weinberg (1989), whose book leads us through a fun exercise that illustrates the ambiguity problem and also provides some serious insights as to possible solutions.
Consider the familiar nursery rhyme: "Mary had a little lamb." Although it's unlikely that anyone will build an information system based on this sentence, it's nevertheless interesting to ask, What does it mean? In order to disambiguate, we can perhaps use the keyword, or dictionary, technique. In this technique, we focus on the keywords in the statement and look at the options, based on various meanings for each. Here we'll focus on the words "had" and "lamb." "Had" is the past tense of "have," so we'll have to use the definition of "have"; we can use "lamb" directly. Here's what we find for "have":
have 1a: to hold in possession as property … 4a: to acquire or get possession of: to obtain (as in "the best to be had") … 4c: ACCEPT; to have in marriage … 5a: to be marked or characterized by (to have red hair) … 10a: to hold in a position of disadvantage or certain defeat … 10b: TRICK, FOOL (been had by a partner or friend) … 12: BEGET, BEAR (have a baby) … 13: to partake of (have dinner) … 14: BRIBE, SUBORN (can be had for a price)[1]
And here's what we have for "lamb":
lamb 1a: a young sheep esp. less than one year old or without permanent teeth … 1b: the young of various other animals (e.g., smaller antelopes) … 2a: a person as gentle or weak as a lamb … 2b: DEAR, PET … 2c: a person easily cheated or deceived, esp. in trading securities … 3a: the flesh of lamb used as food[2]
Accordingly, we could interpret the phrase "Mary had a little lamb" to mean any one of the following:
| Lambic Interpretations | ||
|---|---|---|
| "Have" | "Lamb" | Interpretation |
1a | 1a | Mary owned a little sheep under one year of age or without permanent teeth. |
4a | 1a | Mary acquired a little sheep under one year of age or without permanent teeth. |
5a | 1a | Mary is the person who owned a little sheep under one year of age or without permanent teeth. |
10a | 1a | Mary held a little lamb under one year of age or without permanent teeth. |
10b | 1a | Mary tricked a little sheep under one year or age or without permanent teeth. |
12 | 1b | Mary gave birth to a young antelope. |
12 | 2a | Mary is (or was) the mother of a particular small, gentle person. |
13 | 3a | Mary ate a little of the flesh of lamb. |
14 | 2c | Mary bribed a small person trading in securities who was easily cheated. |
For people who grew up with this nursery rhyme and who read the rhyme to their children each night, this discussion might sound preposterous: "How could any reasonable person interpret such a familiar phrase in so many bizarre, outlandish ways?" But such a complaint is neither fair nor realistic if we expect someone from a different background, and perhaps even a different nationality and culture, to attempt an interpretation based strictly on the dictionary definition of the two keywords. If it can happen with nursery rhymes, surely it can happen with complex software systems the likes of which have never yet been created.
One way of coping with ambiguity is to use not natural language but rather "formal" requirements specification techniques, which we'll discuss in Chapter 28. For obvious reasons, the user and the stakeholders outside the development group typically prefer natural language, and even computer people manage to carry on most of their day-to-day communication in natural language. But even though both groups have some facility for communication in a natural language, they do come from very different cultures; they have a different focus, orientation, and set of assumptions.
Although it may be impossible to eliminate ambiguity entirely, we can attack it in a variety of different ways. Gause and Weinberg (1989) provide some techniques we can use when faced with this all-too-common situation.
Memorization heuristic: . Ask several individuals, both from the development group and from the user/stakeholder group, to try recalling, from memory, the customer's real requirement. Parts that are not clear and cannot be easily remembered are likely to be the most ambiguous. Focus on them and try to restate them with more clarity, so that they can be remembered.
Keyword technique: . As illustrated with Mary's lamb, it often helps to identify the key operational words in a statement and to list all of their definitions, using an authoritative source that the various members of the project environment will accept. Then mix and match to determine different interpretations, as was done with Mary and her lamb. As a quick test on this technique, you may also note that interpretation 1(a) and 1(a) above, "Mary owned a little sheep under one year of age or without permanent teeth," is probably closest to the meaning in the fairy tale.
Emphasis technique: . Read the requirement aloud and emphasize individual words until as many different interpretations as possible have been discovered. If only one of the interpretations is correct, restate the requirement appropriately; if multiple interpretations are correct, additional requirements may need to be generated accordingly. We'll illustrate this point with another investigation of Mary and her lamb.
Other techniques: . If appropriate, try using pictures, graphics, or formal methods to flush out the ambiguity and eliminate it.
Suppose that we saw the phrase "Mary had a little lamb" in our requirement set and were trying to ensure that we understood what the user was really driving at. Saying the sentence aloud and emphasizing individual words might help us elicit any one of the following:
Mary had a little lamb; if this is the case, perhaps the user is telling us that it was Mary's lamb, not Richard's or anyone else's.
Mary had a little lamb; perhaps she no longer has it. Perhaps it's the tense of the statement that's significant.
Mary had a little lamb; thus, the key point may be that Mary had only one lamb, not an entire flock.
Mary had a little lamb; indeed, it was one of the littlest lambs you ever saw.
Mary had a little lamb; the emphasis here reminds us that Mary didn't have a pig, a cow, or even a grown-up sheep. But we might still be misled into thinking she had a baby antelope.
No one technique will work in every circumstance. Achieving the right balance of ambiguity and specificity will be a practiced skill that you will need to develop within your organization and project context. The amount of specificity you need to provide may even vary over time, based on the changing skills of those downstream in the process and their understanding of the domain in which you operate.
Here are our recommendations to find the "sweet spot" in your project context.
Use natural language wherever possible.
Use pictures and diagrams to further illustrate the intent.
When in doubt, ask! When you're not in doubt, consider asking anyway.
Augment your specifications with more formal methods when you cannot afford to be misunderstood.
Train your people to recognize both the problem of ambiguity and the solutions that can be applied.