How to use spikes as a foundation for ADRs
Spikes have been used to validate or investigate a solution since the early 2000s. Perhaps because of their age and wide use, the definition of how to create and use them has grown. You may have heard “Just raise a spike for it” or “Our sprint is 50% spikes” while in your teams. Or conversely, you might not use spikes at all and have unestimateable, XL tickets (or hidden work done by the team in the background) to deal with your unknowns or assumptions. These may be signs that a team does not know how to effectively address their investigation and decision-making process.
Architectural Decision Records (ADRs) are a way to capture architectural decisions along with their context and consequences. ADRs, partnered with the Advice Process and a regular Architectural Advisory Forum (AAF) enable a decentralized way of making decisions which scales beyond the traditional ivory tower of architecture. The ADR / AAF approach has skyrocketed in popularity recently but without careful tending, by a community, they are liable to become another documentation overhead. In trying to write them for everything, you may write them for nothing.
A technique that has worked well for me to address these pitfalls is to use a spike as a question which an ADR will answer.
In Andrew Harmel-Law’s article on Scaling Architectural decision-making, he suggests several key elements of an ADR, including title, context, options considered and consequences. By considering what we want in these elements as we define a spike we can better identify where ADRs would add value and tightly focus the scope of our spikes. Here’s how:
Title
ADRs titles are best expressed as the decision that has been made. This allows those who aren’t involved to quickly understand what to do if they are dealing with a similar situation. For example “Github actions is our pipeline tool of choice” is your architectural decision. But how did you come to this conclusion?
I expect you first asked the question “What tool should we use for our delivery pipelines?”. This question would be the title of your spike, with the ADR title as your answer. This places explicit work within the team to come up with the possible options, investigate them during a timebox and capture the data that was used to reach the decision — which itself becomes the ADR.
Context
In the main description of your spike, you should answer the following questions to provide enough context for the team to investigate.
- What is the value of answering the summary question?
- Why do you need to answer it now?
- Who may be impacted or interested in the answer?
- What are the constraints?
If you can’t answer these questions, park the Spike and bring it back during one of your backlog refinements when you can.
Example:
Options considered
When you create a spike, often there will be an overwhelming number of options you could investigate and opinions you might want to consider. Quickly brainstorm what options you’d like to investigate before playing a spike. This can be done neatly in a refinement session. This makes it easier to scope and timebox the spike. As you explore each option, you’re creating the documentation for this part of your ADR.
And remember: doing nothing can always be an option!
Example:
Consequences
As part of the exploration of each of the options, you should consider the consequences. The last context question “Who may be impacted or interested in the answer” will be helpful here. Considering how each of the impacts or interests of your options the parties you identify in that question will allow you to make a well-rounded decision that will hopefully address the concerns of folks providing advice on your ADR. The easier your advice-givers jobs in reviewing your ADR, the faster you can implement your decision.
Example:
I’ve found the combination of Spike as questions and ADR as answers give more structure to our team’s spikes, enabling us to give more accurate timeboxes and better inform our ADR write-ups. It also meant that ADRs were not only in the realm of technologists. We created more well-rounded value statements and prioritised which spikes we played and when was simple.
Before I close there are some small caveats. For this technique to work successfully, the whole team has to be on board, as it is likely that everyone will be creating and contributing to spikes.
Additionally, this is simplest when ADRs are your architectural documentation tool of choice, but this may also work where you use a change control board or a request/response way of making architectural decisions. I haven’t tried this technique in those scenarios, so anyone who has or does, please get in touch!
