I want to talk about a project I recently worked on — the Help With Prison Visits service — and specifically about how the development team communicated about design.

I spoke briefly about this topic at the Kainos kick-off this year, and it prompted me to finally get around to writing up my thoughts.

The first thing to say about this was that (pretty much) all our design was published in the open, and in fact you can go and read it here:

APVS Open Design Wiki

This was based on the notion of Open Design Proposals, an idea which you can read all about in this blog by Rory Hanratty, You Must Think First, Before You Move.

On Help With Prison Visits we decided early on that we would put this approach into practice — we had the full support of our client and the MoJ Digital team, who were fully committed to an open source by default approach. A very nice place to be and one that comes with many other added benefits which are really a post in their own right.

As Rory says, it’s not a new thing. It felt new to us — because to most of us “Design” with a big D is something that happens in a document that is written and then forever languishes in some form of doc management thingymer.

You can therefore view this as a follow-up to Rory’s blog; effectively a case study in putting this approach to evolving design into practice and doing it out in the open for all the world to see.

The Design/Code Conundrum

The distinction between design and coding is one of those grand philosophical debates that engineers love to have from time to time — or have happen to them.

On the one end of the spectrum there is the school of thought that says code is the ultimate expression of a design and therefore (assuming it’s been written in a suitably self-documenting manner) the only document you’ll ever need.

This is in fact a very purist version of the concept we’re talking about. A pull request should ideally be a design proposal, expressed in code. My final thoughts at the bottom of this article summarise why I think there is still a place for “design” as its own thing.

At the other end lie’th the pit of despair that is the 200 page low-level “design spec”, the mythical “compile-able Word document” that we all used to joke about whilst simultaneously crying into our cornflakes.

Ideas in software — as in politics — are like the swing of a pendulum. Periodically we reach one peak of extremism before eventually being carried back towards something more rational and then on to the next crazy.

The world in which I want to live is that space in between and speaking for myself, this project was the best experience I’ve ever had as an exercise in collaborative, iterative design owned by the whole team. So I think there’s something to it.

Technical Heads on Technical Spikes

Technical Spike is jargon for research.

It may or may not involve building a thing, but at a minimum it should result in a better understanding of some problem or dependency such that the team can tackle it in earnest — or make a decision that it should be tackled.

The wiki has a number of Technical Spikes which you can see listed on the home page.

We came to a common template quickly and this didn’t see a whole lot of refinement throughout the course of the project, other than to remove some things from it.

Looking at a selection of these documents will give you a quick idea of the format:

1. Keep it relatively short

2. Start with a short description of the business requirement in plain English

3. If it’s an integration, describe the 3rd party, what they do and why we’re interested in it

4. Propose a design — how would we use this to meet the requirement?

5. Diagrams are good — we use WebSequenceDiagrams a lot

6. Consider non-functional requirements — all the ‘ilities’ that are relevant

7. Include costs if there are any (licenses, usage)

8. Draw conclusions. If you’ve spent time investigating a thing or building a prototype, say why it’s a goer (or not) and highlight any risks

Someone owns each spike, but our definition of done for these includes peer review and discussion.

Web Sequence Diagrams deserves a special mention as it allows you to very quickly knock together design visuals using plain text, and you can save and share the files in plain text as well.

It has the benefit of making you think about the actors in the system and how they will interact, where functional responsibilities should lie and when something should be a new component to meet NFRs.


Another cool technique we adopted was the use of Change Sequence Diagrams. We were led in this endeavour by Steven Alexander who has written in detail about how it works.

In a way, this part is closer to the original description of ODPs per Rory’s blog. It’s about proposing changes to an evolving architecture in a way that encourages some up-front thinking about the consequences.

A change sequence design

As you can see, we threw these up on a whiteboard in the room and then snapped a copy for the wiki. Simple.

Like a bunch of philistines we’re not even using something like Office Lens.

Again, this is all about “stop and think”. They are quick to produce and force you to think about all the touch points in the architecture that your changes will impact. This is subject to peer review like everything else and was usually a collaborative effort in the first place, because we all miss things.


I’m interested in what you think of this, how you are doing design and what you would include (or exclude) in an approach like this.

Relative to development — and certainly to deployment — design is a relatively low cost activity.

Intellectual effort comes cheap compared to the effort of developing and implementing something, so it is an activity that should be encouraged, and I think this approach does encourage it.

The advantages of using tools like GitHub and Markdown are that developers like them and that they crucially allow designs to evolve as context changes. No more static documents with ‘version’ tables in the appendices!

I found this to be a very rewarding way of working and the benefits ultimately manifested in a happy team and high quality software. You can’t ask for much more than that.