| |

Decreasing the Odds of Misunderstanding

A requirements model is, in simplest terms, a set of labeled propositions: most of it is natural language text. If so, how can you reduce the odds of it being misunderstood? Natural language is vague, ambiguous, unclear, while systems/products/services we make to solve requirements tend to be well defined, at least when they’re made; hence the question.

A lot of effort when doing requirements engineering goes into how to remove just enough ambiguity, vagueness, and get to the level of detail that’s enough to design something resembling “the right” (or simply, acceptable) solution. While this is the case, and there is a lot written and said about how best to do it all, there’s a fairly simple approach to reduce the odds of it being misunderstood, and it boils down to the following: take the model, extract all nouns and verbs in it, assign them their default definitions from a glossary (e.g., WordNet – see below), and ask if these default definitions apply; then do the same for all nouns and verbs in these definitions; repeat, as long as there are resources to do this.

Here’s what it looks like with an example. Let’s say the following is some early statement of requirements.

“When a company needs services of an expert, for a short time, on a specific project or to help close a deal, it can be very hard to identify actual competence, to trust available evidence of reputation, and then, to get to a formal agreement on what to deliver, when, and what to do in case of dispute. Word-of-mouth is still the best tool, but it lacks transparency, structure, and availability. On the other hand, experts need to make themselves available to companies, in a way in which they can provide trustworthy evidence of relevant competence. Both sides need to be able to find each other, and follow a clear process to get to an agreement, having a third party that will mediate the contracting and disputes which may take place. That third party would need to run the marketplace which would match the demand and supply of experts’ time to work on projects and deals.”

Let’s just take nouns. They are listed below.

[‘company’, ‘services’, ‘expert’, ‘time’, ‘project’, ‘deal’, ‘competence’, ‘evidence’, ‘reputation’, ‘agreement’, ‘case’, ‘dispute’, ‘tool’, ‘transparency’, ‘structure’, ‘availability’, ‘hand’, ‘experts’, ‘companies’, ‘way’, ‘evidence’, ‘competence’, ‘sides’, ‘process’, ‘agreement’, ‘party’, ‘contracting’, ‘disputes’, ‘place’, ‘party’, ‘marketplace’, ‘demand’, ‘supply’, ‘experts’, ‘time’, ‘projects’, ‘deals’]

We then grab their definitions from WordNet, the first definition of each. We could take them from anywhere else, including – and interestingly – a technical glossary that may apply, a mix of a technical glossary and WordNet, or say, a corporate glossary.

  • project: any piece of work that is undertaken or attempted
  • deal: a particular instance of buying or selling
  • competence: the quality of being adequately or well qualified physically and intellectually
  • evidence: your basis for belief or disbelief; knowledge on which to base belief
  • reputation: the state of being held in high esteem and honor
  • agreement: the statement (oral or written) of an exchange of promises
  • case: an occurrence of something
  • dispute: a disagreement or argument about something important
  • tool: an implement used in the practice of a vocation
  • transparency: permitting the free passage of electromagnetic radiation
  • structure: a thing constructed; a complex entity constructed of many parts
  • availability: the quality of being at hand when needed
  • hand: the (prehensile) extremity of the superior limb
  • experts: a person with special knowledge or ability who performs skillfully
  • companies: an institution created to conduct business
  • way: how something is done or how it happens
  • sides: a place within a region identified relative to a center or reference location
  • process: a particular course of action intended to achieve a result
  • party: an organization to gain political power
  • contracting: becoming infected
  • disputes: a disagreement or argument about something important
  • place: a point located with respect to surface features of some region
  • marketplace: the world of commercial activity where goods and services are bought and sold
  • demand: an urgent or peremptory request
  • supply: an amount of something available for use
  • projects: any piece of work that is undertaken or attempted
  • deals: a particular instance of buying or selling

So now, we have a larger set of potentially misunderstood nouns, and we haven’t touched verbs, nor adjectives, by the way. As I wrote here, we would normally not just expand the list of nouns as above, but replace some of the nouns and/or their definitions with those that remove any unwanted sources of misunderstanding. And then, we would do the next iteration, which yields even more nouns.

The approach should be obvious. It is not easy to execute – there’s a lot of terms to define, and many definitions to manipulate – but it has the benefit of being simple to explain, and use widely available tools. The above was done with a few lines of Python code with NLTK.

The way this approach, even as simple as it is, starts being very valuable, is when the revised definitions are fed to a local glossary – for the company, for the project, program, or other management structure you have around people giving and solving requirements. 

A note on propositions in requirements models: Since it is cheaper not to formalize propositions, they will most likely be in a natural language. Even if they were written in a mathematical logic, as Spivey observed [1], you still need them to be written as a person would read them – in the end, people, for the most part, need these models in the first place. Hence my observation at the beginning of this text, that requirements models are for the most part natural language text.


  1. Spivey, J. Michael, and J. R. Abrial. The Z notation. Vol. 29. Hemel Hempstead: Prentice Hall, 1992.

Similar Posts