Want your system to last? Get an historian

Where do we put the decisions?

Where I work, you can pick one:

• Architecture decision records (ADRs) to keep technical decisions.
• Design histories to keep design decisions and sometimes user research.
• Policy design histories to keep policy decisions.

And of course there are also commits and pull request descriptions, and tools like Trello and Slack, weeknotes, and email. And conversations. But those things aren’t deliberately designed for storing and publishing decisions.

ADRs and design histories are, though, and they all aim for the same wild goal: decisions as artefacts. That is, keeping the reasons for a decision or set of decisions in a document of some kind, to be referred to when necessary. Alistair Cockburn suggests we “learn to think of development as an assembly line of decisions”. These tools take that literally, causing the decisions themselves to take on a concrete form.

It’s a lovely idea. I’ve never seen it truly realised.

You’ll forget

Institutional memory is powerful because once you understand why things are the way they are, you get to change them. You can take down Chesterton’s fence—that thing you don’t like the look of but can’t remove until you know what it’s for.

But by default you’ll forget. Once your team has forgotten why and can’t find why out, you’ll make fewer and fewer decisions until you can’t change anything and you’re doomed.

You’re lucky if you know enough to make any real decisions at all.

Elite documentation

A good place to keep decisions is inside people’s heads. That works, until they leave. The next best place is documentation. And of course documentation often goes unwritten, and even when it is written, it gets ignored.

But a nice property of decision documents is that they’re more resilient than other documentation.

For one thing, they are meant to go out of date. They reflect the past, not the present.

And they’re all the same sort of thing, so they needn’t be hard to find - just list all of them in one place, and provide a reasonable search interface. The Becoming a Teacher design history has successfully achieved this for design histories across several services. The Teacher Services tech docs auto-aggregate ADRs (and indeed all documentation) for every repo we work with.

Who writes history?

Most of the time, developers and designers. They have very different approaches.

In my experience, codebases tend to accumulate a lot of ADRs at the start, and fewer as they go along. It’s hard to remember to write them—perhaps because in the short term, it doesn’t seem to matter that much. Here’s a chart showing when ADRs were created for some services I work with.

ADRs are little dots, publication date of this blog post is a big red dot. Day 0 is day of first ADR. Data from git.

With design histories it’s the opposite. We keep on producing them throughout the project. Register trainee teachers, for example, which is second from top on that graph, has seen 48 design histories vs 7 ADRs over the same ~3-year period.

Why?

I think it’s easy to mistake delivering a design history for delivering finished work. Developers pick them up weeks later and have to unpack them with recourse to the designer. And it’s also true that there are often more “architectural” decisions at the start of the project, though decision making certainly continues.

But in an important way, designers have got this right. They see it as their job to write down their decisions in an accessible format.

For “policy” decisions, like deciding to build something, or withdraw something, or change the rules, there seems to be little or no precedent for how to record them for the team’s benefit. Ministerial submissions, for example, do record changes, but selectively and for a different purpose.

Yet these are some of the most important decisions of all. We should record them too, and we should expect them to be recorded.

A fair description of a great delivery manager

If we accept documentation is a viable way to store decisions, then we need to remember to write it. We also need to remind ourselves that it exists. That work should be part of someone’s job.

That person needs to be in a position to witness, digest, and write up (or cause to be written up) the decisions the team makes. They also need to be able to retrieve past decisions.

Maybe this role could belong to delivery managers. They’re already responsible for weeknotes. They could become de facto project historians, making written decisions a concrete output of their work—perhaps with a side of spicy, decision-filled weeknotes on a Friday.

A fringe benefit would be them understanding everyone’s decisions, which would probably make them an excellent manager. Their days would involve facilitating various meetings, catching up with colleagues, and making sure the record shows what was decided. i.e. only a little bit different from a delivery manager’s work as it is.

They would be the best-informed generalist in every room. (Maybe that’s a fair description of a really great delivery manager?)

Reflection is intrinsically good

The act of representing work, or just seeing work represented, can help you understand that work.

That could be on the scale of single piece of a project, when you discover problems and inconsistencies as a result of writing it up. Or it could be on the scale of the story of your whole team, or a team of teams.

What would that story be, if you could tell it? How would it read—a gripping linear narrative, or unreadable avant-garde madness?

Total context forever

If you can grasp the true story of your work—if you understand the why—you are in an excellent place to make more decisions.

If you document them well, you will still have the why in the future. Then you will be able to make even more decisions.

That is a virtuous circle.

So if you want your system to last, it might be worthwhile to invest energy in finding and seeing decisions, in housing them somewhere, and consciously using them to interpret and shape the story of your team.