So, do you know how to build a software system for your client? (part 1)
Tags: softwareengineering, agile, requirements, specifications
Published: 2019-06-23 21:56:36

---
title: So, do you know how to build a software system for your client? (part 1)
published: true
cover_image: https://thepracticaldev.s3.amazonaws.com/i/7oj6reqsgjuu3wqwaiae.jpg
description: Managing Requirements and creating Specifications
tags: Software_Engineering, agile, requirements, specifications
---

You're a good developer. May be even a great one. You know your programming language(s) inside out. You're a wizard with databases and key-value stores. You're at ease with functional design as well as OO one. You can Dockerize anything and deploy it to AWS in a jiffy. 

...*but can you build a software system for your client??*

The reason I'm asking is because even though you may have all the skills mentioned above, that doesn't mean you can build a software system for your client. Sure, you can build *a software system*, but by 'software system for your client' I mean a system that does, at a  minimum, what your client needs and, ideally, what they want.    

"Sure", you say, "my client tells me what they want and I build it!". Really?! How do you know that you're building what they want? Yes, they tell you what they want but how do you know that this is what you're delivering? How do you know you even understand what they're telling you? More importantly, how does your client know that you're building what *they* want?  The thing is, building software is more than just coding. Yes, coding is a crucial part of building a system but it's not the only part and -arguably- not even the most important.

There have been [many studies](https://medium.com/specstimate/10-reasons-why-software-development-projects-fail-7200e7c9ae2e) conducted on the [causes of software project failure](https://headchannel.co.uk/6-reasons-why-software-development-projects-fail). They all agree on one thing: The main cause of failure is a combination of requirements ambiguity, poor communication and unrealistic expectations. Let me summarise this in a sentence:

> If your project fails, chances are it will fail because you didn't properly manage its requirements.

Managing requirements involves the elicitation, modelling, analysing and communicating of your client's requirements. That's right, you can be be the best coder in the world, head of a team of super coders but that will not make a big dent in the odds of your project failing. So I'll ask again: 

*Do you know how to build a software system for your client?*

By now you should have caught on to the fact that unless you know how to handle your client's requirements, your answer to the above question should be a resounding NO. Because you may be a great Developer but unless you can manage requirements you're no System Builder!

So, where do you start? You start at the beginning: By understanding what Requirements and Specifications are. 


## Requirements vs Specifications
Even after more than two decades in software development I still get surprised by how many people, even experienced professionals, don't know the difference. They often use the terms interchangeably. This is the road to abject project failure.

Simply put, a **Requirement** is a stakeholder's expression of a need, wish or desire about the system being built. Requirements come in different shapes, forms and sizes and from various sources. Requirements can be provided as:

* formal statements (“The system shall provide a document searching facility”)
* rules (”accounts with monthly deposits larger than $1000 receive a 10% discount”)
* examples (“Joe didn’t have to pay for his coffee because it was his 11th coffee in that store”)
* User Stories
* [Business Processes](https://www.heflo.com/blog/bpm/business-processes-definition/)
* Flow-charts, activity charts, or other types of diagram
* some other obscure way that I can’t even imagine at this point

A **Specification**, on the other hand, is a description of the system behaviour required in order to fulfil or realise a Requirement. So for our “The system shall provide a document searching facility” above, a specification could be something along the lines of specifying how to add some search strings on a search bar. The Specification is just a way of defining how we’re going to realise the Requirement. Nothing more, nothing less.

## The Requirements gap

So let's get this absolutely straight: 

1. Requirements tell us what our client wants or needs. Ultimately, it is our client's responsibility to provide us with the requirements. What we can do is help them identify, refine and validate them. There are a number of techniques to help us achieve that and they will be covered in the next posts of this series.  
2. Specifications tell our client (and our team) how we will meet these requirements in the delivered system. Specifications are essential to building a successful system. They drive the whole development and testing process. To quote [Joel Spolsky](https://www.joelonsoftware.com/2000/10/02/painless-functional-specifications-part-1-why-bother/):

    > "Failing to write a spec is the single biggest unnecessary risk you can take in a software project. It’s as stupid as setting off to cross the Mojave desert with just the clothes on your back, hoping to 'wing it'." 
 
3. Our job as System Builders is to elicit our client's Requirements and translate them to Specifications. 

4. Our client's job is to confirm that the Specifications reflect their Requirements.

This series aims to outline a number of agile methods and techniques that will help you:
* Elicit requirements
* Model them
* Create executable specifications


The gap between Requirements and Specifications is a deep and dangerous one. The next article will show you how to start building a bridge over it, so stay tuned.


*PS*: the articles in this series are related to, and a continuation of, my earlier [post on User Stories](https://dev.to/redfred7/enough-with-the-user-stories-already-2a8a)