Ambiguity and the Right Level of Detail

Key ideas#

The sweet spot#

Leffingwell and Widrig say the question they hear most often is how detailed a requirement must be to avoid misunderstanding. There are two ways to miss:

• Too little detail. Ambiguity rises until nobody can tell what is meant.
• Too much detail. Understanding drops again. Users will not read an overloaded specification, and implementers lose sight of the purpose among the details.

The target is the zone where the requirement is both understandable and unambiguous.

The blinking-lamp example#

Take a requirement for a two-lamp box: if either lamp fails, the other must blink once per second. It sounds clear until the programmer has to choose a duty cycle. Half a second on and half off, or nine-tenths on and one-tenth off? Both blink once per second. For a simple indicator, nobody cares. If the same kind of vagueness describes the power output of a surgical instrument, it could harm a patient.

The authors conclude that the right level of detail depends on two things:

1. The consequences of a misreading in this application.
2. The implementers’ ability to make good choices on their own, or to ask in time.

“Mary had a little lamb”#

Leffingwell and Widrig borrow an exercise from Gause and Weinberg. Look up the dictionary meanings of two words in that familiar line, “had” and “lamb”. “Had” ranges from “owned” to “bribed”; “lamb” ranges from a young sheep to a person who is easily fooled. Combined, they give more than a dozen legitimate readings. A phrase that feels perfectly clear to people who share a background can mean something else to people who do not, and that is exactly the position of developers reading users’ requirements.

Three heuristics for finding ambiguity#

These come from Gause and Weinberg, as presented by Leffingwell and Widrig:

• Memorization. Ask several people, from development and from the business, to write the requirement down from memory. The parts they struggle to reproduce exactly are probably ambiguous. Rewrite those parts.
• Keywords. Pick the key words, write out their possible meanings from an authoritative source, combine the readings, and check that exactly one is intended.
• Emphasis. Read the requirement aloud several times, stressing a different word each time. Each stress can reveal a different reading. If only one reading is intended, rewrite to make it explicit; if several are valid, you may need separate requirements.

Where misunderstanding is unacceptable, move to formal methods such as pseudocode, state machines or decision tables.

The authors’ recommendations#

• Use natural language wherever you can.
• Add pictures and diagrams.
• Ask when in doubt, and ask even when you feel no doubt.
• Use formal methods where a misreading is unacceptable.
• Train the team to recognize ambiguity, not just to fix individual cases.