Challenges in Requirements Analysis: Finding and Understanding the Correct Terms

There are lots of things that make requirements analysis difficult. For this article lets focus on one issue:

What is a Train?

At first sight this looks like a rather simple question and might be answered by having a look at wikipedia:

A railway or railroad train is a connected series of vehicles for rail transport that move along a track (permanent way) to transport cargo or passengers from one place to another place.

This is pretty much what most of us understand when we talk about trains. But when we talk with experts in the various domains that involve trains we might come along these definitions:

A train is a collection of wagons that is assembled during a given time before departure.

A train is the abstract thing that has a unique number and travels on specified weekdays at a specified time from one station to another.

A train is the thing that has a unique number and travels on a specific date from one station to another.

A train is the thing that at a given date and time arrives at a given station and leaves a couple of minutes later.

… and many more

Obviously the various possible definitions of the term train are somewhat related but different. Most of the time experts do have precise words to differentiate between these concepts, but since the different definitions are relevant for different groups of experts each expert calls the concept he is dealing with just ‘train’.

So when you try to gather requirements and designing software you must try to identify these different concepts. How would you do that?

Listen carefully: Often people use additions to a main term in order to differentiate between different concepts. Examples might be: “train in preparation”, “train at a station”

Look out for contradictions: Does somebody describe a train as something repeating every week while another one says something happens at departure? They are probably talking about two different kinds of train.

Collect constraints: What identifies a train uniquely? A number? A date + a number? A date and a track? How does a train relate to a station? 1:1? 1:2? 1:n? Ask the experts for such constraints, ask them if they agree with the constraints identified by others. Don’t stop when you have one answer, but verify it over and over again. It really sucks when 95% of your users use one definition and 5% use a different one. It sucks even more when you find out about it on deployment day.

Look at the documents and systems in use right now: Often header for reports or forms (paper or digital) give cues for constraints. But also intensely used comment field sometimes with obscure DSL  like syntax are pointers to a missing concept. The same holds for abused fields. For example when you have a field that contains mostly the number 10, 20, 30, 40, 50 and 60 sometimes the numbers in between and in few cases the value 999 or 998 I am willing to bet that the records are used for at least two different things and boths aren’t properly modeled as a number.

Find and use the correct terms Domain-Driven Design: Tackling Complexity in the Heart of Software