Summary List Placement
When developers at fintech startup Nubank needed to choose which database they’d use for its customer interaction system, they didn’t rush into the decision. They carefully listed all of the attributes they wanted the database to have — like flexibility and compatibility with existing tools — as well as all the different options, like Amazon DynamoDB and Datomic. For each option, they then listed the pros and cons of each tool.
With all the information laid out clearly, the developers finally chose Datomic and listed their reasoning in a type of document known as an architecture decision record, or ADR.
ADRs essentially provide a template for decision making and are an increasingly popular way to keep track of how and when a technical choice was made.They allow developers to run through the context of any given choice, both to help them come to the best conclusion and keep an easy-to-reference historical record.
For example, a developer may make an ADR to choose a database, like in Nubank’s case, or decide which data encryption method to use.
When developers revisit a technology in a few months or even a few years, ADRs allow them to digest the context behind their past decisions in a readable format. They essentially provide a detailed, clear history which can help guide the future.
“I think everyone who has been programming for a while has had the experience of looking at some code and wondering ‘What idiot wrote this?’ only to discover that they themselves were the idiot in question,” Nubank CTO and cofounder Edward Wible told Insider. “What this underlines is just how easily the context and reasoning behind technical decisions can get lost.”
Losing the context on a decision can make it a “silent, lurking liability,” he added: ADRs can essentially answer the questions “what problem were we trying to solve?” and “why did we decide to do it this way?”
With the rise of agile development — a engineering framework that emphasizes high-speed work though comprehensive documentation and collaboration — ADRs have grown more common. There are several ADR templates on GitHub that thousands of developers have favorited, like an ADR for quality assurance or ADR geared for developers who want to use a text editor.
Especially during the pandemic as remote work separated teams, ADRs can make sharing knowledge and cutting across teams easier.
“One of the hardest things to track during the life of a project is the motivation behind certain decisions,” said senior vice president at Sabre, Michael Nygard.
Writing down that information also helps new employees understand the codebase better.
“I’ve joined companies before and it just seems like there’s so much stuff that everyone just knows, but that, I don’t know,” GitHub Actions engineer Jonathan Clem told Insider. “And it’s really frustrating because you just feel like there’s this big uphill battle to feel like you’re sort of one of the group and that you share that context that everyone else has. And so what ADRs do is they take all that institutional knowledge and they make it concrete.”
ADRs should be ‘simple and stupid’
Making ADRs can help companies choose technologies that will set them up for long-term success and optimize for key goals of the organization, like performance or reliability, ThoughtWorks CTO Rebecca Parsons told Insider.
For example, listing pros and cons through an ADR can help developers choose the lightest possible tools that are easy to set up and integrate into the rest of the software architecture.
The tools developers decide on should be easy to switch out as needed and based on employees’ skill set. For example, if a company doesn’t have any developers who can code using the Clojure programming language, then it should not pick a tool that relies on Clojure.
Developers should make sure that the ADR documentation is very crisp and clear,” David Van Couvering, senior architect at eBay, told Insider.
Organizations should keep ADRs “simple and stupid” so that any developer can read and easily understand them, adds Cassie Shum, head and technical director of cloud partnerships at ThoughtWorks.
An ADR should also be no more than one or two pages long. Clem advises not to spend too much time concerned with the semantics of an ADR. Also, don’t treat it like documentation: ADRs are meant to be a history of a decision, while documentation is about how things actually work.
“If they are also living documentation, you have to go back and alter them,” Clem said, which defeats the purpose. “Maybe you did the wrong thing at one point, and you want to remember that decision so that you can learn from it, and if you go back and alter the ADR to reflect the current state, you lose that.”
If the organization decides to change its technology, it should create a new ADR for that decision and update the status of the old ADR to “superseded.” However, it should not get rid of the old ADR because it’s important to have a record of their previous decision.
There are many ADR templates out there and Oliver Kopp — a researcher who built the Markdown Architectural Decision Records project on GitHub — suggests using a consistent format throughout the company. Read existing ADRs on GithHub can be helpful for inspiration.
“If you use ADRs, you will have a huge knowledge base of decisions you’re making and frameworks taken,” Kopp told Insider.
Many ADRs have the following parts, according to Tanmay Deshpande, chief architect at Schlumberger:
- Title and unique identifying number: The title should be short and to the point
- Decision: The final choice.
- Status: The status can be “proposed,” “accepted,” or “superseded.” If an ADR has been superseded, that means a new decision has been made that overwrites the old decision with a new ADR.
- Context: Provide the reasoning why the decision was made. Expand on the background of the decision and possible alternatives.
- Consequences:Write what would happen if the decision is made, including its pros and cons. It’s important to make a list of all possible outcomes, both good and bad.
NOW WATCH: Why these Gucci clothes are racist