This post is the first in a series of posts that will begin to take a look at each of the various stages of a software development project. Of course no two projects are exactly alike so we’ll start by looking at each stage at a very high level and explain broadly why we go through each phase, our general approach and the reasons for it. We’ll delve into some of the intricacies in later posts!
In an earlier post (“If you fail to plan you plan to fail”) we outlined the process we use to organise a project from start to finish. The idea behind this was to reassure readers that we employ a proven methodology which ensures everything runs as smoothly and efficiently as possible. Following on from this we’re now going to look at one of the first stages in a little more detail – the “Requirements” stage.
Why do we need to outline the Requirements at the start of a project?
As the name suggests, a Requirements document sets out what the client requires of us – it tells us what we must do in order to meet their needs.
In Stephen Covey’s famous book “Seven Habits of Highly Effective People” the second habit is described as “begin with the end in mind”, the idea being that if you don’t have a clear idea of your destination then you are unlikely to get there (and if, by some fluke, you arrive in roughly the right area, you’ll have taken a very circuitous route). So having the project requirements clearly defined before you start work is an essential pre-requisite for success and efficiency.
However, there are several less obvious reasons why it is smart to start out with a clear picture of the requirements. It gives the client something against which to measure the product that has been designed and delivered. Without this document how do they know whether the software will do everything they want, in the way that is required? The flip-side of this is that it enables us to demonstrate that we have delivered everything the client asked for – using this document we can show that we’ve ticked all the boxes that were agreed at the start (and get our final stage payment!).
Finally, it enables us to give the client a quote for how much the project is going to cost and how long it is going to take. Clients like us, wherever possible, to give them a fixed price up front – but if we don’t have a detailed and accurate set of requirements then it’s very difficult to do this.
Isn’t this just common sense?
Yes it is. However, in real life common sense is seldom common practice. In theory you would never start a project without the requirements clearly outlined and formally agreed – but in practice it seldom works out like this!
One of the most common reasons is pressure of time. Business moves fast these days and we are realistic enough to recognise that our clients are seldom given all the time they would like to complete projects. When deadlines are tight there’s an anxiety to “just get started” and a temptation to rush the preparation of the requirements specification.
By doing this you create risk – the risk that things will go wrong, take longer to solve, and come in over budget and beyond the deadline. The more detailed the requirements specification the fewer grey areas and the less risk of surprises and issues.
Some clients don’t worry about this – they think they are handing over these risks to us, so it’s no longer their problem. This is a fallacy – if we can see grey areas that have not been de-risked we’ll simply cover ourselves by building more time and money into the quote. If the client wants to pass risks on to us it will cost them more money. On the other hand, if they do more work themselves at the start and de-risk the project before passing it on to us, we can give them a tighter and keener quote.
When faced with such situations we have to be pragmatic. We share the client’s sense of urgency, and don’t want to delay things unnecessarily, but we also recognise that time spent now will almost certainly save effort and money at the end of the day.
Another reason is that the client, although expert at what they do, does not know what information we need from them. They have all the information in their head but just don’t know how best to present it to us – so we have to help them.
An alternative approach
So, it makes sense to start with a clearly defined set of requirements. And yet in practice projects seldom work quite like this. This has led to the development of a somewhat different approach – and one that we will sometimes employ if it is deemed appropriate.
This involves starting out with a set of requirements that contain the main objectives but which leave many of the details unresolved. We then start designing, coding and testing to get things moving. As the project progresses the more detailed requirements start to take shape and we add them to the specification as we go along.
This is a viable and practical way of working, but there’s a downside – we cannot give clients a fixed price for the job at the outset.
How do we go about preparing a Requirements document?
All things considered, clarifying the requirements at the start is probably the way to get the best result. However, even with the most detailed requirements specification things will change – you’ll discover unexpected issues and the client may change their mind on a few points.
Sometimes the client presents us with everything we need, clearly laid out in exactly the detail we necessary to get started. But in practice this is seldom the case.
A client may call us very early on in their thinking process, with only a very rough idea of what they want. In this case there will need to be a series of telephone calls and meetings to get us to a point where we have those requirements pinned down and agreed upon. Or they may present us with a requirements document that requires further work. In these situations we’ll quiz the client and ask them a series of questions to get all the information we need.
The parameters of this discussion will be pre-set, however, by the fact that whatever we’re being asked to design will have to interface with a variety of other systems that are already in place. These systems will provide inputs, from which we’ll have to create outputs, and so the discussion will be shaped, right from the start, by the nature of these inputs and outputs. It’s a case of picking up these little threads, following them through, and making sure they all connect up correctly.
To do this we’ll generally employ what is known as a “use case” approach. This is a list, or basic diagram, defining interactions between an “actor” (a human or an external system) and a system, to achieve a goal. This is a simple way of describing what the system has to do and very useful when building up a requirements specification.
What does a good set of Requirements look like?
Each project tends to be very different so the requirements documents can vary enormously from one job to the next.
Some projects are R&D based, and in these instances the requirements will generally be quite loose and flexible. If it’s a safety related project, however, we will need much more detailed requirements.
As far as safety is concerned, each industry, whether it’s the railways or avionics, has a set of regulations and mandatory requirements that will have to be satisfied. A system engineer or a safety engineer, who is probably independent of ourselves and the client, will conduct a hazard analysis and prepare very detailed set of pre-requirements that have to be included with the overall requirements to address those hazards. These have to be tracked through the entire development testing process in addition to the requirements the client gives us.
Apart from theses mandatory safety requirements there will be two other types of requirement.
The functional requirements specification should describe, as fully as possible, what the system needs to do – what functions it needs to perform.
Functional requirements should be atomic – ideally the whole project will be broken down into its smallest component parts, accompanied by clear structural statements. The requirement for each part should be measurable, testable, traceable and detailed enough to define all aspects of a need without further breakdown. We further define these terms as:
- Measurable: The functionality can be measured to ensure the end product conforms to it.
- Testable: A test can be performed to ensure that the requirement is met
- Traceable: Each atomic requirement is uniquely identified with a number that is traced to all subsequent documentation (Designs, Test Specifications)
Non- functional requirements
There will, however, be other criteria, not directly related to how the system functions, that need to be taken into consideration. The client may include these other requirements in their specification or we may need to draw out this information in our discussions.
These non-functional requirements do not define what the system actually does. These will generally cover the following
- System performance – speed, memory usage, start-up time, etc.
- Safety/environmental considerations – safety case requirements, size, temperature, etc.
- Development constraints – use of particular hardware/operating system/language, comms protocol, etc.
- Interfaces (human and machine) – Priority of GUI features, interface protocol, etc.
- Fault reaction/tolerance – actions when a fault occurs, acceptable degraded working, etc.
- Future support – warranty, in-service support, maintainability, etc.
- Use of existing equipment – life extension of equipment.
- Use of COTS equipment – hardware or software.
If you have a clearly defined set of functional and non-functional requirements in place at the start of the project it makes everything considerably easier for all concerned. The expectations are clearly defined so there’s less chance of misunderstandings. This doesn’t mean everything will run smoothly and exactly to plan (we wish!) but it does help to minimise risks, speed up progress, keep costs down and enhance efficiency.