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.

References

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