Writing Requirements Unambiguously

sax face

Writing requirements without ambiguity

This is one of the harder parts of writing good requirements. Marcus tells us to avoid it with a good example here. Jerry Aubin at Seilevel has written an outstanding post on the subject, The art and science of disambiguation. Jerry starts his post with a gripping example from Weinberg and Gause:

  • Mary had a little lamb.

What exactly does this phrase mean to you? Here are some possible answers.

  • Mary owned a lamb.
  • Mary gave birth to a small sheep.
  • Mary ate some mutton.
  • Mary conned a mild-mannered person.

As Jerry shows, ambiguity can result from variations in the use of language – a much more subtle problem than in variations in the symbolism people associate with words.

Jerry points out that one of the key ways to avoid ambiguity is to leverage a shared context for conversation. This is very effective, but very difficult, especially when you consider how little overlap in context there is between different members of the same team. We talked about this in one of our earliest posts, Intimate domains, where we highlight the distinct contexts of different players on a typical software team.

A requirements manager must be able to communicate within each context, and translate between contexts to serve as an effective communicator.

domains of expertise

As our diagram (re-used from Intimate domains) shows, people in each area of expertise have a predominantly independent context. And within that context they have unique interpretations of meanings for words. More than jargon or symbolism – many words carriy a unique, rational interpretation within each context. In that post we go into more details on how to navigate these areas of expertise.

The authors of the ambiguity handbook (pdf link available in the seilevel post), highlight what we believe to be the insidious challenge of ambiguity when writing an SRS (or PRD) – unconcious disambiguation.

Unrecognized or unconscious disambiguation is that process by which a reader, totally oblivious to other meanings of some text that he has read, understands the first meaning that comes to mind and takes it as the only meaning of the text.


The PRD (or SRS – see Requirements document proliferation) is the most important document to clear of ambiguity, because it is a document that is intended to communicate across context more than other documents in the requirements process. We talk about these role transitions a bit in our post, Software requirements – process and roles. A review of that process puts context and communication in perspective.

One thought on “Writing Requirements Unambiguously

Leave a Reply

Your email address will not be published. Required fields are marked *