The Problem With Requirements

Requirements documents are halfway between a peace treaty and a Christmas list.

I have an email from Glenn. He needs to get a piece of software built and wants to know if I can make it for him. At the end of his email, he says, “I’ve gathered all the requirements,” and offers to send them over.

He says it so confidently: “I’ve gathered all the requirements,” as if they were strewn across the ground and he just picked them up. The phrase sticks with me because I have no idea what to expect. Will it be a Word document, an Excel sheet, a PowerPoint, a mind-map, a set of Jira tickets, or Trello cards? Maybe “all the requirements” will be high-level business priorities (“The system will allow us to take payments”) or maybe they will be low-level descriptions of how to integrate with specific payment APIs. They might cover non-functional requirements (“it will be secure”). Will there be user stories? Wireframes? Designs? Or will he just say “design is required.” All of the requirements is such a bold claim. No edge case left unturned, no feature left behind. I can’t tell if Glenn’s confidence is that of someone who knows more than me or less.

People talk so confidently about requirements that for a long time I thought there was a concrete definition that had been kept secret from me. Perhaps a secret Business Analyst code, that details precise standards to follow. Maybe there’s an ISO standard for them. But every time I start a new project with a new person, out comes their own idiosyncratic way of documenting requirements and we meander through to a finished product. I’ve accepted that, but, I still find it weird that we pretend there’s a shared concept of “requirements” when there are so many options; scaled by T-Shirt sizes or Fibonacci sequences or SCRUM poker cards, prioritized with high, medium, low or MoSCoW (Must do, Should do, Could do, Won’t do). I find MoSCoW the strangest. The difference between “Must” and “Should” is subtle. “Could” is making a rod for your own back. And don’t even get me started on won’t. “Won’t run on Windows 95”, “Won’t be written in FORTRAN”, “Won’t cause the downfall of capitalism.” I’m always surprised this section isn’t longer.

Requirements serve a different function, depending on where you are in the software development life-cycle. In the early stages, you need high-level ideas, to tease out, understand, and check what you’re building. In the latter stages, you need exact instructions. But every team has their preference and style. Some people only process information in the form “Given I am a user wanting an app, then I will write the requirements”, others hate this format. When it comes to requirements, there are so many opinions.

A friend of mine is looking for a boyfriend. She’s running the boyfriend hunt as if she were assessing the market to procure a major commercial contract. She reckons she has been through every single man between the ages of 28 and 38 on Tinder. The phone actually reached the end, she says. She swiped and there was no one left to swipe.

She has a requirements list too. “At least 6 foot tall”, “no hair on back”, “rich” and so on. They’re very much functional requirements (“Must be tall,” “Could have a holiday home in the South of France”, “Won’t be very sweaty”).

Perhaps I am spotting patterns where there are none, but it is strange how similar this feels to Glenn’s list. The list has not helped the hunt though. She did find someone that matched every item on the list, but he turned out to be a nightmare. She thinks the list needs to be longer. After her latest date, she added “Not a jerk” to the list. I guess it’s good to have some non-functional requirements too.

Back to Glenn though. He sent his original email to a few people across the organization, using a scattergun approach to try to find someone to help. One woman he emailed works in IT procurement, another man works in internal consultancy. She looks after purchasing IT systems, he looks at ways to help the organization run efficiently. The four of us get together to work out what to do with Glenn’s list. My colleagues sit on opposite ends of a requirements spectrum: she wants to “bottom out the requirements” so she can work out what to procure, getting more detail, more specific. He wants to be “more high level”, getting back to the core problem.

“What’s the problem you are trying to solve?” he asks.

I’m reminded of a requirements gathering course that covered the “Five whys”, a technique developed by Toyota to determine the root cause of a problem. It’s exactly what it sounds like: a work-sanctioned version of a six-year-old asking “why”, until either you have an answer or everyone is so frustrated they abandon the project. During the course, after explaining the concept of the five whys, they got us to practice on each other. We dutifully sat around and asked each other why five times, uncovering root causes galore.

In the wrong hands, the root cause is is either “because my boss said so” or “because of the Big Bang”. It’s easy to get too fundamental a root cause.

We discuss Glenn’s problem and my colleague quizzes him on the benefit of the work he’s trying to do.

“It’ll make the website easier to use,” Glenn says.

“That’s not a benefit,” the consultant says.

“If it’s easier to use, people will be able to complete tasks quicker?” He tries again.

“That’s not a benefit.”

Poor Glenn. He makes a third stab at it. “If staff can work faster, that’ll free up time so they do more work and save money.”

This is grudgingly accepted as a benefit. I can’t help noticing the requirement hasn’t changed and I wonder what we gained.

My other colleague asks if she could have more detail on the requirements. Glenn tries to describe what he wants but is told off for “solutionizing”.

“We want to stay solution agnostic at this point,” she tells him.

I feel for Glenn. He’s doing a strange mental tongue-twister, simultaneously imagining the future state he wants, perfectly, covering every detail, while not thinking of a specific implementation. I’m not sure people are able to think at this level of abstraction.

As a result, Glenn has created a monster. A list of requirements and app ideas, mixed together into one frequently mutually-exclusive list. His personal preferences have become “critical business requirements”. After years of being held hostage by IT, he’s learned that the way to get what he wants is to say things are “business requirements”.

Some of these are easy to spot. He likes radio buttons and hates drop downs so added “Must have radio buttons”. Others not so much so. Being able to take payments is a business requirement, but when Glenn describes what he wants the emails to contain we enter the grey area of “business processes”.

What’s missing is a good business analyst. But even with one, it’s tough to get right. At times business analysts need to be prosecution barristers, cross-examining users about their requirements, trying to produce a Columbo-like moment to unravel the web of preferences knitted into their “requirements.” It’s not even that users are consciously lying. Often they’re confused or simply haven’t thought about their business processes in a way that’s conducive to developing an application. And why should they?

As time goes on, people start to become entrenched. Where do software solutions end and business processes begin? It is a political minefield as people jostle for control of the requirements list.

My lovelorn friend has found someone. Not through Tinder, for once, but a friend of a friend when she least expected it.

“How’s his back?” I ask.

“Surprisingly hairy,” she tells me.

Her list is cast aside. Not all requirements really are requirements.

You obviously need requirements if you’re making a product. How can you write code if you don’t know what you want to, you know, encode? But I’ve become deeply suspicious of requirements documents. Their function is often political rather than technical.

They don’t represent every flow and process in the application. I’ve come to believe that code itself is the only way precise enough to represent the totality of the business logic. You can write a document, but when you actually write code, you spot edge cases that have been missed.

I’ve heard people say that writing is thinking; that the process of constructing an argument over several thousand words organizes ideas into a coherent structure. The same thing is true for coding. The code you write is the solution to the problem. Any documents written along the way are notes to help you reach that solution.

Building a product is an on-going conversation. The more complex the product, the harder the conversation. The more people involved, the more different viewpoints to be taken into account.

Writing the requirements is part of the dance that brings software to life. I call it a dance, but depending on the project, it may be a war. Not every project is like this, but at times documents become like treaties for demilitarization. Writing requirements is a defensive act, each one inked onto paper the result of a protracted battle or negotiation: fine, we won’t use accordions, but I do want drop-downs. Each side deploys their weapons to get their preference onto the paper: the “research” that supports their view, the cost calculations, the business needs. It’s not that research isn’t valuable, but when faced with a stakeholder who keeps saying how “friendly” Comic Sans is, you can see the temptation to cherry pick a study that supports your view. You can’t afford to A/B every decision.

Once the list is produced, a set of religious edicts carved into stone, you can move forward. Now, the list is a political item to be weaponized. For changes you want, allow them as omissions, for changes you don’t, point to their non-appearance on the list. “You signed this off. We can add it, but that’ll be a change request and will hit the timeline.” If you’re a third party supplier, this is a great time to ask for more money. The requirements list may be part of a contract: see Schedule 1 for details of the deliverables. But the list never describes all of the deliverables that need delivering. It’s a backstop to stop one side going too far off-piste.

My colleague in procurement is satisfied that Glenn has put enough detail into his requirements. She has produced a MoSCoW list.

“We’ll put out an RFP,” she says. A Request For Proposal. This will be sent to the market to for companies to bid on. Unfortunately, no companies respond. Glenn’s list is too specific and no one has a product able to meet his needs. The list has been too bottomed out. There are a couple of companies that can meet most of the requirements, but when Glenn looks at the systems, he finds the interfaces unusable.

I wonder what the chances are that Glenn, like my friend, will meet a software application at a party when he least expects it.

I don’t think it’s possible to produce a full list of requirements and hand them over for delivery, no matter how appealing that sounds. Successful products are on-going conversations between everyone involved. Think of the Agile Manifesto, the closest thing software development has to a religious text: “Business people and developers must work together daily throughout the project.”

Requirements lists are a shadow of the Platonic product, they at best hint at the sort of areas that are important. If you’re buying something you’re picking between options on the market. If you’re building something the process of delivery needs to tease out what’s needed as the product gets ever closer to the state of “good enough to go live.”

Glenn shrugs the RFP off. He’s decided now that maybe he doesn’t need a piece of software after all. Having given up on the IT Department, he thinks he may be able to do it all himself via email and a couple of Excel spreadsheets.

“What about the requirements?” I ask.

“I think we might be able to de-scope some of them,” he says.

Media techie, developer, product manager, software person and web-stuff doer. Head of Corporate Digital at BBC, but views my own. More at pittster.co.uk

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store