A program is an incredibly precise thing. It does what it has been programmed to, and nothing else. (Or, if it does do something else, we raise a bug report and fix it). It represents a specific expression of our answer to a problem. Unfortunately, while the program is specific, the problem is often vague. To make matters worse, we're often vague as well.
Let's take an example of a program.
10 FOR I = 1 TO 10
20 PRINT "HELLO"
30 NEXT I
(Because who doesn't write in BBC Basic, these days?).
"I've written you a program," you proudly tell the customer.
"Great!" The customer replies. "What does it do?"
You, wanting not to be vague, say "10. FOR I = 1 TO 10...". Before you've even got to the exciting second line, the customer's eyes have glazed over. You realise you've been too detailed, even though you were definitely precise.
"It prints "Hello" ten times," you try.
"Brilliant!" the customer beams. "That's just what I needed."
Happy to have fulfilled this (admittedly bizarre) requirement, you settle down to reading dev.to and wait for the next taxing assignment.
Unfortunately, an hour or so later, the customer comes back, frowning. "You said that program printed "Hello" ten times. But I've been sitting next to the printer for an hour and nothing's come out."
When we change levels of abstraction - whether that's to talk about our program with another developer, or about requirements with a customer, or about progress or problems with a colleague, we run the risk of introducing vagueness. Whenever we introduce vagueness, we run the risk of misunderstanding, or making a mistake, of inducing a mistake in someone else.
I worked for a long while for a B2B company that provided a system that, in part, dealt with our customer's customers. There was a terrible habit of using the term "client" to refer to either my company's customers, or their customers. When your story starts "As a client...", and you've already introduced vagueness, you know you have a problem.
So much vagueness revolves around terminology. "Print". "Client". Often words are overloaded, with sometimes the business domain (the world the customer inhabits) clashing with the technical domain (I've spent long hours discussing the performance of the performance module, until I started to doubt the word was real).
What can we do about this?
The trick is to be precise without becoming more detailed. If we've selected the level we're conversing at appropriately, then getting more detailed is only going to slow the conversation down and may lose clarity. Or the customer.
1) Identify Vagueness.
Spot terminological clashes, confusions, or repetitions. Also, in this category, are areas that the customer is uncertain about, even when pressed.
"We probably want a page where the user can update their email."
"Do you want it or not?"
"I think so."
Another manifestation is in bug-finding. "It looks like the call to the backend is timing out." Is it timing out or not? If we can't tell, what do we need to do to be sure? I can't count the number of times I've been deep in the code before I realised that what I thought had happened (or what I'd been told had happened) hadn't actually happened. Or had happened in a different order.
2) Agree terminology.
"I know you use the words "client" and "account" interchangeably. For the purposes of this software and project, we're going to try to always use "account". Is that OK?" Document your project glossary in a place where it can be referred to easily. Stick to it (or change it and all the places the old terminology was used), even when in casual conversation.
3) Reduce Uncertainty.
All the usual tactics - show an early version, echo back requirements, add logging or metrics. If a problem, or a requirement, is enveloped in a fog of vagueness, reducing the vagueness is an important step - you may not be able to address the actual issue until the vagueness has gone.
4) Recognise Unreducible Uncertainty.
It may be that there is some vagueness nobody can dispel. The customer may not be certain whether they need a feature or not. You may not be able to determine whether or not an algorithm will perform well enough with real volumes. The only thing you can do is prepare to be wrong - be ready to change to another option. If you had to nail the business analyst to the wall to get them to decide, there's a good chance they've got it wrong, so design and implement your software to minimise the impact of changing it.
5) Don't Add to the Fog.
Correct yourself when you misuse terminology. Challenge colleagues when they seem vague. Make sure that tentative decisions don't get misremembered as certainties.
Being precise rarely takes a significant amount more time than being vague, but it does take effort and attention. It's easy to get sloppy around, for example, teammates, and carry that sloppiness into conversations with less attuned people. But recognising the need for clarity helps avoid problems, and it helps resolve them when they weren't avoided.
Or something.
Top comments (0)