Removing ambiguity

Ambiguity is not vagueness. “Handle a request with no signed-in learner” is a perfectly clear English sentence; what it lacks is a decision. It admits a 404, a crash, showing another learner's courses, a redirect — each a legitimate reading of the same words. The requirement names a set of possible behaviours and stops, leaving the choice to whoever builds it.

Removing ambiguity is the act of adding worked examples until exactly one reading survives. Each example is a concrete case with a stated result, so it contradicts every reading that would have produced a different result — and rules them out. Add the case “a request with no signed-in learner is redirected” and the 404, the crash, and showing another's courses are all gone. The set has been narrowed to one, and it was narrowed before a line of code was written.

The test of a statement in a spec is simple: does it leave many readings open, or does it pin one? An abstract phrase — “handle bad input,” “show something reasonable” — opens readings; a worked example — “a request with no signed-in learner is redirected” — closes them to one. The same spec usually carries both: the prose frames the intent, the examples pin the behaviour.

Select a statement below. The figure reports whether it is an ambiguous requirement (many readings) or a pinning example (one reading), and why. A spec that is all prose can be argued with; a spec whose examples pin every behaviour cannot.

On the Portal — the learning platform this course builds — the spec for the learner-enrollments page opens with the abstract intent: serve a learner their own courses and handle a bad request gracefully. Left there, “gracefully” is a set of readings. The spec closes them with worked examples: Portal.Enrollment over an enrolled learner, a learner with no enrollments, and an unauthenticated request, each with a stated result. The not-signed-in case pins the one reading that survives — a redirect, never another learner's courses.

The fragment below is spec text: the abstract Definition-of-Done phrasing set against the pinning Given/When/Then settled at F6.5 · Views with HEExThe HEEx rung that server-renders the catalog and reconciles the learner route into the protected /my/courses.View the spec ladder →. The contrast is the whole lesson — one line read many ways, three examples that leave one.

# the abstract intent (one line, many readings until pinned):
#   "the page must handle a bad request gracefully"
#   readings: a 404? a crash? another's courses? a redirect?  ← undecided

# stories (F6.5) — the worked example that pins ONE reading:
#   Given a request with no signed-in learner,
#     when GET /my/courses,
#     then it redirects — never another learner's courses.

surviving_reading = "redirect, never another's courses"  # the one the examples leave
removed           = :the_other_three             # 404, crash, another's courses — ruled out

A requirement is a set of readings; ambiguity is the missing decision, not vagueness. Removing it is adding worked examples until exactly one reading survives, each example ruling out the readings it contradicts — and the narrowing happens in the spec, before a line of code is written. The Portal closes “handle a bad request to /my/courses” to the redirect reading. That closes the module: examples are the specification, they are living documentation that cannot drift, and they remove ambiguity. The next module names which artifact carries which part of all this.

The sources behind removing ambiguity, and where it connects in the course.