Engineers at CECG are constantly looking for new ways to bring more value to our customers and this principle extends to our documentation and knowledge sharing.

In our experience, we have come across many organisations where information about current projects and how things work are scattered across many resources:

• comments in code (often useless, used as an excuse for bad function names, design, and sometimes laziness of developers)
• outdated and often overlong docs on company wiki
• information in people’s brains built up over the years while being a member of that team (these are by far the most valuable and accurate).

As a consultancy focused on solving the toughest infrastructure and software problems, we constantly find ourselves facing similar architectural challenges on different engagements, where we often repeat the same research effort just to end up with the same conclusions but very different document structure supporting that decision.

Luckily there is a new and better way of capturing this information that takes into account the iterative nature of the project lifecycle and standardises the structure of the produced document - Architectural Decision Records (ADRs).

What is an ADR ?

ADR is a short document describing the intentions, motivation and main forces in play that produced significant architectural decisions and was collaboratively agreed by the engineering team.

Why ADRs?

Let’s be honest, no engineer likes to spend hours producing documentation that no one ever reads - after you’ve presented it to the stakeholders. Typically, it goes out of date shortly after you write it and finally ends up cluttering search results on the company wiki. ADR’s for the rescue!

ADRs were born out of the need for living documentation that can keep up with the fast developing trend of agile delivery. First introduced by Michael Nygard in late 2011 , ADRs gained quick popularity by being a good fit in the iterative agile delivery process. Rather than produce all documentation upfront - waterfall mode - ADRs allow recording of architectural decisions in real time during project development. Each document is immutable, meaning any change in an existing decision would require the author to append a new document, rather than change an existing one. This builds a log record of why’s and what’s of the project for future users, developers and stakeholders.

Why it makes sense for engineering teams

At CECG’s engagements, we form hybrid teams of CECG and client engineers. ADRs make sense for the engineering teams in which we take part and advocate for them even in the teams that we are not a part of. It is inevitable that as projects evolve over time, the complexity grows linearly at best. ADRs provide a linear history of the architectural decisions.

ADRs are a form of knowledge transfer. All architectural decisions are captured in a single location and knowledge is distributed more equally among all team members during the lifetime of the project. New joiners can review past and recent decisions taken, together with the rationale and circumstances that affected them at the time. This brings clarity and transparency while providing a mechanism for knowledge transfer of the project architecture, where often many tradeoffs are taken in order to satisfy higher priority requirements.

ADRs avoid the problem of rehashing old technical discussions when the context hasn’t changed. Have you ever found yourself in meetings repeatedly questioning the same architectural decision over and over? Or gone over a code and questioned “who wrote this and why”? Then checked git commits to find out that it was you a month ago?

ADRs promote evidence-based decisions over personal preference. The process of writing an ADR requires engineers to explicitly say why they are picking one technology over another.

ADRs are a mechanism to disagree efficiently. No engineering team agrees on everything, with a methodical ADR process, these disagreements are captured in the context, a decision is made, and the team moves on.

Studies show that to remember information better, it is beneficial to write them down. This is how the brain works; writing engages additional cognitive processes (rather than reading, or listening) which make it easier to recall information later. On average people remember 10% of what they hear, 20% of what they read and 80% of what they see. So if all your team members review your ADR, you’ve already increased the chance of them remembering by about 50%. (Hint: If you add a diagram explaining the decision that takes it up to 80% !)

ADRs can be the mechanism for cross team knowledge sharing. Ever wondered if your team could use this new shiny technology/language that would solve all of your problems and hugely simplify the code, but were unable to get any sprint time to do the spike? According to Conway’s law , large organisations are often divided up according to the business functions exchanging information between one another, which is then reflected in the architecture of their internal systems. Due to the number of the departments and their teams, it is almost impossible to track every project evolution between all of them. Very often they have the same or similar technological challenges and based on their maturity/project nature they might have similar forces at play that affect their architectural decisions. Internally shared ADRs allow engineers to share the knowledge across those departments easily. For example, if another team already produced an ADR about a specific database and decided not to use it, your team can draw a lot of valuable information from such an ADR and come to a conclusion on their own project a lot faster.

ADRs prevent knowledge silos. When an ADR is written and then reviewed by all team members, the decision automatically becomes a team decision. By sharing ownership of those decisions, the team members’ engagement increases as they share responsibility for the success of the project.

Why it makes sense for CECG as a consultancy

At CECG we get good insights and exposure to a variety of technologies and languages across our various engagements. One of our greatest assets is our collective knowledge; by producing and sharing ADRs we ensure that not only our engineers, but also all our clients are benefiting equally from it. Adhering to our clients confidentiality, our Engineering Leads share the high-level learnings from their respective ADRs and they all gain the collective experience from all of our engagements.

By sharing the knowledge gained from producing ADRs across engagements, our engineers can leverage the learnings from trialling a technology or spiking a solution to a problem that we have already faced in a different engagement. “_Which tool to use to create infra? Which language to use to write a certain plugin? How to design a multi-tenanted Kubernetes cluster?” _ CECG’s internal knowledge is always the starting point for our engineers when facing a new problem. It is quite possible that the problem has been seen and solved before, and even an in-depth solution may be available.

Usually they are solutions to common problems that recur over and over and of course are not confidential. Sharing the learnings from ADRs ensures that the value our consultancy brings to our clients is not limited to knowledge of the people we place in a particular engagement, but the collective knowledge of all our consultants. This ultimately results in less time spent in research and spikes and ensures faster delivery to our clients.

Why it makes sense for the client

Let’s start with the big one. It will be cheaper in the long run! ADRs are just one way that we do continuous knowledge transfer with our clients. These documents and this knowledge stays with the client after the engagement is completed.

Our preferred methodology is to work directly with client engineers, even pairing for the majority of the work. However, sometimes client engineers might not be available and delivery speed is still the priority. In such cases, ADRs provide a mechanism for senior client engineers to have input into any decision that will affect them in the future. ADRs allow new team members to get up to speed faster. By pointing them to your ADRs, they can get good insight into the past challenges and solutions that were implemented in that project. They can also start contributing earlier, as knowledge gained by reading ADRs will give them a good base knowledge to drive their implementation decisions according to project constraints and highest priority requirements.

When ADRs are written before the implementation and shared with our clients, they have the ability to influence the decision early, saving engineering effort and its own costs. This allows them to feel more engaged, while their engineers are assured that they are going in the right direction with every significant decision taken. Producing ADRs for all significant decisions works both ways; proving confidence of engineers and improving visibility within the team, which results in better relationships between stakeholders, engineers and the consultancy.

When our clients decide to continue the project on their own, our support subscriptions allow our clients to continue using ADRs and obtaining input from CECG for technical validation. This will give them the confidence they are making the right technical decisions after we have stopped having full time engineers in the project.

To wrap things up

Architectural decisions are very difficult to get right, sometimes tough to agree on and often hard to identify individuals accountable for them. They’re usually very expensive to change later on, and very often are related to more than just functional requirements of the system. Therefore, as engineers we should ensure that the decisions made are the right ones given the circumstances. At CECG, we believe that the best way of proving that is by producing a structural document which lays out the thinking process leading to the conclusion that is collaboratively reviewed and shared with all stakeholders - ADR!