Introduction
This 2 part blog post discusses the fundamental building block of any software project, the software specification document.
Everyone who is involved in developing software will have come into contact with a software specification in some way, shape, or form. It could be just a quick note saying “can you make me a routine that parses some text” or it could be a multi page document that describes every single requirement in explicit detail.
In my experience most are somewhere in-between these two extremes.
Having been involved in both the creation of these types of document and also in implementing the software solution (sometimes both for the same project), it is clear that different people have different expectations of such a document.
In part one I use an analogy of building a garden shed to highlight some common issues when interpreting a specification document. Part two will aim to describe what should be in a software specification document, with the intention of starting a discussion on the subject.
Introduction to Part One
In part one I will discuss what can happen if a solution is created based on a fixed specification, a fixed price and also with little communication between the different parties involved.
This is — in my experience — quite a common occurrence and can lead to some unintended results. It should be noted that everyone involved in these projects works with the best intentions and any untended results are not necessarily the fault of anyone in particular.
An Analogy
For the purposed of this example, lets look at it a different way. Forget software, architectures, languages, in fact forget all technology. Let’s go with something nice and simple that everyone is familiar with, lets specify a garden shed.
____________________________________
Garden Shed Specification
Purpose
The main purpose of my garden shed is to store all the things that I don’t want to keep in the house or outside in the garden. Mainly bicycles, tools and seasonal items (cushions, kids toys, bbq etc.).
It would also be very nice if there was space to create a working area which I can use for repairing, assembling, painting etc.
Aim
The shed should be rectangular, have a roof, be secure and weather proof. It should fit within the designated space and in no case exceed the area in the garden that has been reserved for the shed.
Requirements
To fulfil the purpose and aim of this project, the shed should meet the following requirements:
- Maximum width = 4 meters
- Maximum length = 6 meters
- Standard door hinged on one side
- Made entirely of wood, except for where this is not feasible (e.g. the roof)
- Roof should be of the “flat” design, with a small pitch to allow run off.
- Floor should be solid and flat (i.e. not bare earth)
- Be high enough so as to allow comfortable movement for someone of average height (183cm)
Project Completion
The project will be deemed completed when the shed can be used for it’s specified purpose and meets the aims as described above.
Points to Note
As this is a new build house the owner is not on site all the time, only visiting when the main housing contractor reaches an agreed milestone. This is usually only once per week.
____________________________________
So, as the contractor for this project you use this specification to order the materials and estimate how long it will take. You agree a fixed price for the work, with an hourly rate being used for any additional tasks. When everything arrives you get started, it is quite a simple task so you make very quick progress and within 3 days you are putting the roof on.
The owner of the property arrives at the site and checks on your work. He looks around and agrees that everything is according to his specification and is generally happy. However when he closes the door he notices that it becomes very dark, then he realises that he forgot to specify any windows. So he asks if you could fit a double window along the front wall next to the door.
This is quite a simple, it only involves the purchase of the window frame and a few small alterations to the woodwork in the walls. Within a few hours the roof is finished and the new window is installed.
Once all this is completed the owner visits again and mentions that he recently visited a friends house where the guy had just finished creating a “man cave” for himself. Your customer really liked this idea and asks if a few extra items can be installed, namely a fridge, space for a small TV, speakers hung on the wall and a small kitchen area suitable for a sink and gas burner. To allow this he has asked the main housing contractor to run water and power to the shed.
Again, this is all ok and just extra work which means extra money for you. The structure of the shed does not need to be changed to accommodate all these additional requirements.
The main contractor for the house lays the water and power to the shed and leaves them “open ended”. For you this means that you need to adapt the walls and foundations of the shed to accommodate the services, as they ended up on the opposite side of the shed to what you hoped.
When everything is installed your customer has a look around and notices that everything seems a bit cramped, even though the shed is 4 by 6. You correct him and point out that the shed is actually 3.6 by 5.2 as these are standard lengths for the wood you used. Your customer reaches for the specifications and points to the requirements section, making reference to the width and length. When you point out that these are “maximum” dimensions and that the shed was only required to fit “within” the space he realises his mistake and apologises.
After a few minutes he confirms that he would really like more space and asks if you can make the shed higher and add a small mezzanine level where he can sit and watch TV. He makes a point that in the specifications he does not state a maximum height and would not affect the footprint so this shouldn’t be a problem.
You tell him that unfortunately you only used old railway sleepers as a base/foundation and that they would not be strong enough to support the extra weight of the shed. The railway sleepers are sat on the sandy ground with no structural support. Again you point to the specification that makes no requirement as to the material used for the base, just that is has to be solid and flat, which it is.
The owner argues and complains that you are not being flexible and you failed to understand what it is that he wanted in the first place.
Notice that nothing the owner has asked actually breaks or contradicts the specifications. Also notice that the builder has fulfilled the purpose and aims of the shed, it is watertight, secure, fits within the given area and has enough room to store all the things required.
So what now? The owner has the shed that he specified, but it is not the shed that he actually wants. The contractor built what he was asked, but now he has an unhappy customer. From an outsiders perspective this project has been a success, there is physically a shed in the back garden and it has stuff in it. However from the view of those involved in the project it has to be considered a failure, even though nothing went wrong and no-one did/didn’t do anything they were/were not asked to do.
The following are some of the reasons that prevented the contractor providing what the owner ultimately wanted:
- A lack of communication between the contractor and the project owner.
- A lack of communication between the main house contractor and the contractor for the shed
- The specifications were written by someone who probably had little knowledge of construction
- By specifying “maximum” dimensions without also giving a minimum, or specifying a specific measurement there was to much ambiguity
- The wording of the specification was very generic and open to interpretation, words such as “should” could have been replaced by “must” so that it is clear.
- Not enough research had been done by the customer into what exactly he needed/wanted
- Feature creep was introduced once the project was no longer a “blank canvas”, once visualised new features became easier to see
When starting the project the contractor decided to use wooden railway sleepers as foundations instead of more solid concrete ones. This was because the project was fixed price and he already had the sleepers left over from a different project. Starting with a concrete foundation ran the risk of “over engineering” a simple solution, the customer could have complained he was paying for something that was unnecessary. The same goes for the use of standard lengths of wood for building the frame, standard lengths results in less cutting, less waste and quicker building.
Conclusions
In this example the contractor could argue that he showed great flexibility and went above and beyond what he was initially asked to do. He would probably feel that any criticism is harsh on him as some of the changes made were quite substantial, resulting in a shed that was nothing like what had been initially specified. After all he also had the option to simply build what was originally specified, nothing more and nothing less.
The project owner will probably feel let down by the contractor because he was not able to provide the solution he was ultimately looking for. He would probably have the opinion that he hired a professional so that this kind of thing could be avoided, he just says what he wants and finding the solution is someone else’s problem.
In order to provide what the customer ultimately required, would mean tearing everything down and starting again from scratch. This would have been rework to the extreme and unlikely that the contractor would have been able to obtain additional payment from the customer.
The contractor could have also over engineered the initial solution in anticipation of the changes to the requirements, this would have been a financial gamble from him as it was a fixed price contract.
As can be seen in this situation neither party did anything wrong, so how did it end up in such a mess? In my opinion there were 2 things that could have been done at the start to prevent this situation:
- The customer should have done more research in to exactly what they wanted, whether that be searching on the internet, looking through magazines etc.
- The contractor should have been involved earlier in the project and had a role in creating the specifications, or at the very least time should have been allowed for feedback from the contractor. If involved earlier, issues such as the wooden/concrete foundations could have been avoided.
Nice article Darren!
I think 2. is the most important thing. As the contractor you are the one with experience. As such you need to take a critical look at the specifications handed to you and *advise* your customer based on that. Together with your customer you create the better spec version 2.0. 🙂
Shhhh, you are spoiling the surprise of Part 2… 😉