Finding the "Sweet Spot"
One of the most difficult challenges 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 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. 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 (Figure 23-1).
Figure 23-1. Light box exercise
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 interviewing, so the requirements writer can refine the specification with clear user input. As an example of an effort in the natural language style, let's look at the following requirements specification [Davis 1993].
This specification is fairly tight and would be quite adequate for most purposes. More important, it reflects the way the device user intended it to 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 23-2.
Figure 23-2. Possible lamp duty cycles
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. 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, 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 on how well those doing the implementation can make the right decisions or at least ask questions when 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 specification 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 milliseconds ), and other factors; otherwise , the power delivered will not be right, and the device will operate incorrectly. Figure 23-3 summarizes this dilemma.
Figure 23-3. Ambiguity versus understandability
The goal is to find the sweet spot ”the balance point where 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 23-3, you lower both ambiguity and understandability. For example, if we provided timing diagrams, complete with timing tolerances, to an unsophisticated user and if we maintained that level of specificity throughout, the user may well not be able to understand the specification 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 inability 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 certainty you must provide so that your system works as intended.
Mary Had a Little Lamb
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 remove ambiguity 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 skip this short section.)
For the rest of us, let's have a little fun, courtesy of Gause and Weinberg , whose book leads us through an exercise that illustrates the ambiguity problem and also provides some serious insights about 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 this example, 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 use the definition of "have"; we can use "lamb" directly. Here's what we find for "have."
And here's what we have for "lamb."
Accordingly, we could interpret the phrase "Mary had a little lamb" to mean any one of the entries in Table 23-1.
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.
Table 23-1. Lambic Interpretations