Bringing ADR’s to my company
Bringing ADR’s to WGU⌗
Firstly, the context necessary to understand this post and the benefits of ADR’s (architectural design records) can be found here.
There are moments in every engineers career where they look at a codebase either as a newcomer or as a seasoned vet of that repo and they go, “why did we do X.” The more pervasive this issue this is the more you will benefit from ADR’s.
"Why did I do the thing?" -- you in 12 months
An ADR is simply put a record of any design decision made in a codebase. Technically speaking this is meant for architectual decisions (hence the name) but as a proponent of if its good then you should take it too far, you can and possibly even should use ADR’s more extensively. Using it as a form of decision record log in your codebase can really eliminate the previously mentioned scenario. That new engineer, or perhaps future you can refer to these documents and get a sense of how decisions were made and how certain things came to be.
There are a plethora of ways to create an ADR but my suggestion is to follow this convention.
Filename: 001-adr-sample.md
# DECISION NAME
## Date
{DATE}
## Status
{STATUS}[accepted, proposed, rejected, deprecated]
## Context
{CONTEXT}
## Decision
{DECISION}
## Consequences
{CONSEQUENCES}
Name⌗
The name should be intuitive enough that it is easy to understand what the decision is. Short and sweet. I would caution against more than 1-2 sentences.
Status⌗
The status’s of these proposals are pretty easy to understand. You Propose a change or decision and then either Accept or Reject it. If something changes later and the decision is no longer relevant or is changed you may Deprecate the decision.
Context⌗
The context is any information that would help another developer or product manager understand why a particular decision was made or the information related to the decision. This section is usually a bit longer than the others and can be as lengthy as you would like.
Typically, I aim for 1-2 paragraphs.
Decision⌗
What decision was reached. Remember not to include any “why’s” in this section. Thats for the Context section. This section is usually 1-3 sentences.
Consequences⌗
This section can be “living” in that you can update this section as you discover new information. Not every definition of ADR’s wants to allow this mutability, but I feel this section should be especially in high discovery or PoC work.
Benefits⌗
I really like how the github develop blog puts it. The ADR’s are not for you.
They are for:
- future you
- your peers
- your future peers
I couldnt agree more. The primary benefit is reducing the “Why did we decide to put a lambda there in our infra?”