How to Write a Decent Spec

Anyone who has given it a go knows that writing specifications is hard work. In fact, at times it seems almost impossible. Which probably is the reason why the practice of using specifications is shunned and dodged whenever possible. Which is bad.

However, if one finds oneself working in the field of railway interlockings, they cannot be avoided. Which is good. So why is it hard to write a good one? And how do you do it?

To me, the main difficulty in writing a good specification is choosing an appropriate level of detail. Let me explain what I mean with this. Software development is a journey from fluffy abstract ideas (‘it should be safe’) to gritty concrete code (‘ExtIsRed := if …’), with the ambition that some of that fluffyness is actually captured in the final code; not an easy task. The fact that the person with the fluffy abstract ideas is usually not the same as the one who writes the code does in no way make this easier. In fact, these persons serve very different purposes in the development process, one making demands and the other one implementing a software product that has to meet these demands. This is where the specification enters the picture. The specification serves as the bridge, or the interface, between the two.

At this stage, perhaps the point I was trying to make becomes a bit clearer. Since the specification serves as a bridge between the user and the implementer, it has to fulfill two purposes; it has to be understood by two parties, and those parties can be quite different sorts of characters regarding education, skills, ways of expression and even personalities. The specification should be detailed enough so that demands and requirements are expressed in a clear and understandable way, but also not too detailed in order to leave some space of manoeuvring to the implementer.

If it is so hard writing good specifications, is it even worth trying? the reader may ask. Well, if one has any ambition at all concerning user satisfaction, or following safety regulations, then the answer to the second question is yes. In fact, as pointed out earlier, specifications are often mandatory when developing safety-critical systems.

So how is this seemingly impossible act accomplished? As with most things, writing good specifications is a question of the right people employing a proper method. With the right people I mean people who can serve as the bridge between users and implementers. This means that they should be very well acquainted with the domain, preferably experts, but also have a fair idea of how the specification will be used. When it comes to safety-critical systems such as interlockings, the specification will first serve as input for the implementation; then it will be used as grounds for verification. The implication is that the requirements formulated in the specification should not only be clear and understandable, they should also be verifiable.

As a choice of method, I would go for some kind of formalism, given my habits. However, this is not for everyone. In general, it might be a better way to write the specification in natural language, but with a rigour and precision inspired by formal systems. This includes giving careful descriptions of all the different types of objects mentioned by the requirements. It also includes giving proper definitions of all the particular notions and relations that relate these objects to each other. Having laid such a foundation, the actual requirements can then be written in the clear, understandable and verifiable way we long for.

In the end, never aim for a perfect spec. A decent one will do.

Text and Photo: Daniel Fredholm