Martin Colebourne

One of the concepts in the Agile movement is that the product is the spec. In other words, the running code should be considered the master reference, rather than some form of detailed specification that says how the software ought to work.

Why is this? In other industries, highly detailed specifications are a crucial part of the process and are a prerequisite to production beginning. Consider the detailed designs created in the automotive industry, or the blueprints required for a building. Why should software be different?

Before we can begin to answer the question, we first need a workable definition of what a specification is. This is actually very hard, because there are many different types of design documents, diagrams, requirements lists and other forms of documentation in use. Some of these are more complete than others: requirements documents, sketches, partial designs and prototypes are all part of the process of developing an artefact. However, in this article, we are interested in one particular type of deliverable – a full specification – that describes the finished artefact in sufficient detail for it to be built. I therefore propose the following working definition.

A full specification is a complete representation of an artefact in an alternative form, in sufficient detail for it to built exactly as intended. 

OTHER INDUSTRIES

Full specifications are an essential part of many industries. In the automotive industry, detailed specifications of every part are created, along with the production systems that will be used to create those parts and assemble them during mass production. In architecture, detailed blueprints for a building are prepared and signed off before any construction begins.

Creating these specifications is a significant investment in time and money, so why is this done?

Although they may be expensive to produce, specifications are vastly cheaper than actual production and the plans are much easier to iterate than the real thing. Working with specifications first allows for the design to be perfected before production begins.

Detailed specifications also allow the process of building to be planned efficiently. For example designing an efficient production line, with appropriate levels of automation. In the architecture example, specifications allow for planning of the construction sequence and timing: which trades are needed when, which materials are required and when they should be delivered.

However, there are also artefacts that are produced without the creation of a full specification.

In the film industry a huge amount of effort goes into the planning of a film and the creation of detailed storyboards and other sketches and prototypes, but there is nothing that approaches a full specification. Handing the plans to a different crew and asking them to make the film would clearly lead to a different result.

An artist might create numerous sketches for a painting, but there is no point at which they create anything approaching a full specification.

When writing a novel, an author may sketch out the overall story, write chapter lists and character explorations. But they would never create anything like a full specification of the book.

Indeed, in these cases it is not clear what a full specification would look like. How could you describe a novel in an alternative form that would have sufficient detail to reproduce it? Perhaps the only thing that would come close would be to write the entire novel in another language first. This would clearly be an unnecessary and expensive step.

So, far from being a strange and surprising idea, it is clear that there are many fields in which a final artefact is created without the need for a full specification. It is a practical, useful, or even essential step in some cases; and extremely complex, expensive and unhelpful in others.

SOFTWARE

What would a full specification for a piece of software look like? Software is a highly complex, interactive and non-physical product. Describing all of the possible states and interactions would be very difficult. Code itself is a description of all of this, and it is a very complex and very efficient description. An alternative form would have to be code in an alternative language, some form of pseudo code, or a massive collection of diagrams and descriptive text.

Could such a specification be valuable? The answer is no: since creating code is not intrinsically expensive in materials or manpower, creating such a specification would not be cheaper than making the code itself.

Plus, if we assume that a full specification was created in some form of pseudocode, or as complex diagrams (rather than as actual code in another language), then it would not be possible for it to run. This means that it would not be possible to check that it works and debug it. It would also be impractical to get feedback from stakeholders, as there would be no way for them to try it out, and the specifications themselves would be too complex to be consumable.

As a result, there would be no value in producing something so detailed. Working directly with the code, and producing intermediate running versions with part of the functionality is clearly preferable – and this is what Agile proposes.

POSTSCRIPT

This may seem to be a clear win for the Agile mindset, but we should’t rush to that conclusion. An extreme Agile viewpoint would suggest that there is no point in doing any significant form of design – just get coding straight away and develop the product iteratively with no overall plan.

However, the arguments above have only demonstrated the futility of trying to create a full specification for software. They say nothing about the value of sketches and less complete design work in planning a product.

Take another look at the examples above – there is lots of design work and planning in the film industry, artists sketch incessantly, and many writers plan before they write. The right question is not whether a full specification makes sense for software (it doesn’t), but what kind of design work does make sense and how it should be integrated successfully with the iterative construction of the code itself.