What’s the point of a specification?

Specifications kill quality

Ignitr just moved in to a new office. As a young fintech startup the process of engaging with one of the biggest property freeholders in the UK was somewhat daunting. From negotiating the licence to overseeing the office redesign and fit-out, it seems that when dealing with institutions, an agreement has no value unless it has been written down.

But does writing down our agreements actually work? Anecdotally perhaps not. On the day that we were due to move in, we arrived to find that engineering had let the side down. The door was on the opposite side to the plan, the internal office (designed to the millimetre around a bespoke meeting table) had been built much larger than planned and there were a host of other minor issues. It was pretty clear that the design specification hadn’t been looked at by the engineers who were doing the job.

And this got us thinking:

Do engineering specifications work? Even a bit?

In life as well as at work, we write down our agreements with other people every day. Each day we’ll leave notes on the fridge or send a text to our partner reminding them to pick up dinner. At work our natural instinct is to be even more disciplined; we routinely attempt to capture any important agreement in writing, by email or perhaps by way of a more binding “specification of work” to be carried out.

Why do we do this?

Our world is built on agreements. They form a necessary part of our relationship with ourselves, with our future selves, and with others. And we write these agreements down, to be able to reference them accurately and to bind ourselves and others to a future state. When we make a to-do list, keep a journal, share our thoughts on social media, we create a written contract with our future selves as well as with those around us. We contract with institutions throughout our day-to-day lives, sometimes implicitly (conditions of carriage, byelaws, store returns policies), sometimes explicitly (here’s the design schematic showing where we want the door to be). Typically these contracts help the world work efficiently by seeking to predict (or determine) the future.

Yet in social situations we very often choose not to seek such a rigid approach to outcomes. We often value social cohesion and collective agreement at the expense of a deterministic outcome (as social beings we often compromise). Whilst we expect a receipt from the teller when we’ve paid for (but haven’t yet received) our lunch order, we very rarely seek an advance written contract from our friends when splitting the bill at dinner. If our partner forgets dinner, few of us will immediately call our divorce lawyers to claim for breach of our marriage contract. In some sense we are making an emotionally and intellectually different type of agreement. These agreements are indeed more nuanced, more sophisticated than a simple transaction for a future state.

Why is this? If we compare written contracts with the more socially useful unwritten agreements:

• written contracts are often bilateral, between the individual and either him/herself or with an authority. Unwritten agreements are more typically multilateral and collaborative, with many people working towards achieving an outcome (“Let’s all meet for a drink after work to celebrate Steve’s birthday”)
• written contracts usually have independence between the producer and consumer of value, whereas unwritten agreements are often between people who act both as producers and consumers of value in the transaction
• written contracts are often highly deterministic. They assert relatively hard, inflexible future states on to the world (and often equally hard alternative consequences in the case of failure). Unwritten agreements are rarely so tied to the solution, being more focused on the collectively agreed goal
• written contracts tend towards a predetermined means to reach the outcome (you will deliver this to me on this date at this cost). Unwritten agreements can often be far more flexible, as long as they remain true to the overall goal. In this sense written contracts are quite often “fire and forget”
• unwritten agreements involve high degrees of ongoing communication: “checking in”, reconfirmation, feedback & consequent calibration of actions along the way
• unwritten agreements are part of a series of agreements where our choices are influenced not only by the immediate commitment, but by the unspoken chain of agreements stretching out both into the past and into the future.

Many organisations routinely approach agreements to deliver software in much the same way as services are procured for an office refit or for infrastructure; taking the contractual, outsourced, commotised approach, adopting a written contract and all it’s attributes. A design specification is a hallmark of a written contract, and all its implications.

However, game theory unavoidably applies to human decision making. If you are only ever commissioning one outcome from your supplier, perhaps a written contractual agreement with a design specification makes good sense. In a match with only one game, we can (at least in theory) identify the “win” state, and abandon the cost of making more socially orientated decisions; you can indeed “fire-and-forget”. But software engineering in almost all circumstances benefits from adopting a looser, more collaborative approach. Without doubt, delivery of complex software solutions will always be improved by increased communication, earlier customer review and more frequent feedback, flexible collaboration and trust based relationships.

When commissioning software by contracting “one-off” transactions (using specifications), customers rarely get what they want because game theory applies. In just one such game, the prisoners dilemma, it is in all parties’ interests to collaborate until no more than one round before your opponent chooses to cheat you. When customers contract only a single round of software (perhaps with the tease but no agreement to engage in future work), they build in an automatic failure to collaborate. If the players truly intend to agree further agreements in the future, why adopt contractual tools that cripple any chance of success? In situations where the benefits of using unwritten agreements (collaboration, communication, trust, interaction and responding to change) are valuable, game players should clearly seek to adopt these more appropriate methods of working together. By writing a specification the player declares the game over and the outcome concluded.

As a software engineer, how many times have you asked a question about the business need, only to be told to “see the specification”?

We finish this story where we started. Despite the initial teething troubles, the team at Canary Wharf group came through in spades. They took immediate (same day) action to start to fix the problems, committed to resolve all issues and even offered us additional and valuable services at their cost. They have communicated and worked with us to meet our needs. We’ve been highly impressed with their professionalism and we owe Tarun, Myles, Steve and his team huge thanks for keeping our business running throughout a challenging time. What we’ve achieved together is what all supplier/consumers should do: use a written contract as a jumping-on point for a collaborative, trust-based relationship, beginning a chain of (unwritten) future agreements to enable the long term successful outcome for all.

This article is reprinted from a blog post on ignitr.eu.