There’s a common pattern in working with existing or legacy projects, where a new team or team member comes on board, chats about some issues with the code with the project team/owners, looks at the code and says “WTF”. Sometimes because its just not the way they’d solve the problem, other times because it’s just really terrible code (this is less often the case than many people imagine though).

And quite often a discussion will take place between the developers and the project owners about the gap between business needs and what was delivered. This discussion may even touch somewhere along the lines of, “they other developers said they did the things they were supposed to, but it still doesn’t work like it should!”

If your first reaction to that is, “the original developers were dolts!” you’re probably in the wrong.

There are all kinds of reasons for business need-code divergence. One of the most common is confusing business requirements and technical specifications when planning and writing the software. Given both that it’s something I’ve written about before and the recent US holiday, I’m sharing with y’all this week.

Specifications: no substitute for requirements

Having spent weeks, months, or possibly even years thinking about the end product, it’s not surprising that clients have a preconceived notion of exactly what their application is going to look like and exactly how each part is going to work.

When you put together a project plan and start developing, there are two typical ways to do it: there are specifications and there are requirements. Confusing the two is a common mistake in early stage projects, which is why it is easy to end up with a beautiful application with little value.

So just what are the differences between specifications and requirements? Requirements are the ‘what’s necessary’ question. What do you need to do? Specifications are the ‘how.’ How are you going to do that?

The destination is not the route

Consider this scenario. You’re out on the street in Istanbul preparing to head to the Istanbul Modern to take in some Turkish art prior to leaving the next day. It seems fairly far away and you don’t have your own car, so you find a taxi to get there.

The first thing you do after getting in the taxi is to tell the driver where you want to go. You’ve seen the map and which streets offer the most direct route, so you may decide to tell the driver what roads to take to reach your destination. At that point, you may find yourself sitting in a traffic jam, which would have been avoided if you had allowed the driver to take his preferred route, the route that went around the traffic that he knew to expect.

What you’re doing in telling the driver the destination is providing requirements. Requesting a specific route is providing specifications. If you provide your requirements to the driver, that you want to get to museum and you’d like to get there by 2 o’clock, then your driver can take this information, and based on his knowledge of the city and its traffic patterns, decide what route to take to ensure your requirements are met. Even with your map of the city and feigned knowledge, your own specifications will almost certainly fail.

If you happen to know all the winding roads in the city of seven hills that might work out for you, but chances are pretty good the only outcome from specifying your route rather than simply providing your destination is going to be a slower trip, at best.

Requirements are destinations, specifications are routes.

Requirements and goals

It’s possible, too, that our driver might have told us that given the traffic congestion, our limited time, and short distance, that it would be in our best interest to walk or perhaps to take a different mode of transport.

On the street in Istanbul, we stopped short in talking only about requirements. Here we’re still relying on the driver as only a technical expert to decide on and navigate a route through the city’s narrow and congested streets. We arrived on time at the museum but were somewhat underwhelmed by the museum. Had we discussed our goals with the driver, there might have been a different final outcome.

Our goal was to enjoy some Turkish art in the one afternoon we had left. Implicit in this goal is that we want to get the best and most unique experience in the shortest amount of time. If we knew that our driver knew something not just about driving cars and about choosing routes through the city but also about the city itself, including its museums, we could have added the the goal of our trip.

With the driver’s aid, we might have gone to a different museum altogether. “An afternoon in Istanbul? No, no, you want the Museum of Islamic Art!” You are skeptical but take the driver’s advice anyhow and you may be surprised by how absorbed one can become just in tiling alone.

Specifically yours,
Ben

 

More like this

• A short side journey on Git workflows and Django projects (This Old Pony #71)
• The problem with fat models, or, an OOPs mistake (This Old Pony #69)