Documenting Cloud Architectures and Projects with Architectural Decision Records(ADRs)

In the world of software development, making decisions regarding the architecture of a project is of utmost importance. These decisions can have a significant impact on the project’s success, scalability, and maintainability.

However, capturing and documenting these decisions can often be overlooked or undervalued. This is where Architectural Decision Records (ADRs) come into play.

What is an Architectural Decision Record and Its Benefits

Architectural Decision Records, or ADRs, are like special notes that help architects remember important choices they made when designing a project.

They’re like a treasure map that shows how the project’s design was decided and why those decisions were made.

Imagine you and your friends are building a big LEGO castle together. ADRs would be like keeping a journal of all the important decisions you made while building it.

This journal helps you remember why you chose certain colors, shapes, and designs for different parts of the castle.

Using ADRs helps everyone in the team understand why things were built the way they were. It’s like telling a story about the castle so that even new friends who join later can understand why things are the way they are.

Having ADRs keeps everything organized and helps the team work together better. They prevent the team from making the same mistakes again and again. So, it’s easier to build the castle and make it even better as time goes on.

Moreover, ADRs promote collaboration and knowledge sharing within the project team. By documenting architectural decisions, team members can easily understand the rationale behind specific choices and contribute to the discussion.

This collaborative approach fosters a sense of ownership and shared responsibility, leading to better decision-making and ultimately, a more successful “Castle” aka IT Project.

Format and Content of an ADR

The format of an ADR typically consists of the following parts:

1. Title: A clear and concise title summarizing the decision.
2. Status: This indicates the current state of the decision, which can be one of the following: “Proposed,” “Accepted,” “Superseded,” or “Deprecated.” “Superseded” means a newer, better decision has replaced it, and “Deprecated” means it’s no longer recommended or actively used.
3. Context: Describes the background and situation leading to the decision, including the problem, requirements, constraints, and other relevant information.
4. Decision: The heart of the ADR, specifying the chosen architectural approach or solution in a clear and straightforward manner.
5. Rationale: Justifies the decision by explaining the reasons behind choosing the specific option, considering pros, cons, risks, benefits, and trade-offs.
6. Consequences: Discusses the expected outcomes of implementing the decision, covering both positive and negative effects on the system’s performance, maintainability, scalability, etc.
7. Alternatives: Lists other considered solutions briefly and explains why they were rejected in favor of the chosen decision.

It’s important to note that the format of an Architectural Decision Record (ADR) can vary according to different authors and teams, resulting in variations in level of detail and document structure. While the core elements like title, context, decision, rationale, consequences, alternatives, and related decisions are common, some authors propose alternative formats to suit specific needs.

One such example is the Lightweight Architectural Decision Record (LADR), which advocates for simplicity and maintenance in a markdown format. LADR suggests keeping ADRs concise and straightforward, using markdown language for ease of readability and version control.

This flexibility in formats allows teams to tailor ADRs to their preferences and project requirements while ensuring the essential information about architectural decisions is effectively captured and communicated.

Additionally, some ADRs might not include all the described sections. For instance, a decision might be imposed upon a team, and the ADR may focus on documenting the decision’s consequences and the lack of participation in the decision-making process.

Approving an ADR — Different Ways and Finding the Right Balance

To approve an Architectural Decision Record (ADR), there are various ways:

1. Individual Approval: Sometimes, a single person or authority reviews and agrees to the ADR through email or document review.
2. Team Consensus: In a teamwork environment, the ADR is discussed in a meeting, and everyone provides their input. Approval happens if most or all team members agree.
3. Architectural Review Board (ARB): For big projects or crucial decisions, an Architectural Review Board of experienced architects evaluates and approves the ADR.

Finding the best way to decide is important. A strict process can be thorough but slow down the project. A more flexible approach can be quicker but may lead to mistakes. The process should fit the project’s needs, ensuring both efficiency and good decisions.

Documentation in AWS Projects

Alright, imagine you’re building a really cool and gigantic (And Expensive) LEGO city in your room. You have so many colorful LEGO pieces, and you’re excited to create houses, roads, cars, and even a big castle!

Now, when you build your LEGO city, you probably draw plans and blueprints, right? These are like your secret guides, showing how everything fits together. In AWS projects, they have something similar called “architecture diagrams.” They are colorful maps that show how the different AWS services connect, just like how roads and buildings fit in your LEGO city.

But sometimes, even with these awesome diagrams, there’s something missing. Just like you might forget why you put a cool car garage next to a candy shop in your LEGO city, people involved in AWS projects sometimes forget why they chose certain AWS services.

And that’s where the “Architectural Decision Records” come to save the day! It’s like writing down all the smart choices you made while building your LEGO city. For example, you might write, “I picked this cool red brick for the roof because it’s stronger and looks amazing!” In AWS projects, they write similar records, explaining why they picked certain AWS services.

For instance, you can record the reasons behind selecting Terraform over CloudFormation or opting for ECS instead of EKS.

Imagine you invite your friends as new builders joining your LEGO city project. They look around and see all these cool buildings, but they’re confused. They don’t know why you put a castle next to a space station, and they can’t figure out how things work together. It’s like being lost in a sea of bricks!

In AWS projects, when a new team member comes in, they feel the same way. Without the special logs of Architectural Decision Records, they might not understand why certain AWS services were chosen, and it can be tricky to put everything together like a big puzzle.

ADR Example for an AWS Project

#### Architecture Decision Record (ADR) - Choosing Terraform over CloudFormation for New AWS Project
##### Status
Accepted
Approved by: The Cloud Architect (notanotherca@cloudprovider.com)
Date: 06-07-2023

##### Context
We are starting a new AWS project to deploy and manage our infrastructure in the cloud. As part of the project, we need to decide on the appropriate Infrastructure as Code (IaC) tool to provision and manage AWS resources efficiently and consistently.

The two main options under consideration are Terraform and AWS CloudFormation. Both tools are popular and widely used for managing cloud infrastructure, but each has its strengths and weaknesses. It is essential to evaluate these factors to make an informed decision that aligns with our project requirements and goals.

##### Decision
After careful evaluation and consideration, we have decided to use Terraform as our IaC tool for the new AWS project.

##### Rationale
The decision to choose Terraform over AWS CloudFormation is based on the following factors:

- Multi-Cloud Support: Terraform is a multi-cloud IaC tool, whereas AWS CloudFormation is specific to AWS. By choosing Terraform, we keep the option open to extend our infrastructure to other cloud providers in the future if required.

- Declarative Syntax: Terraform uses a declarative syntax, which allows us to define the desired state of the infrastructure without specifying the sequence of operations. This makes it easier to manage complex infrastructures and maintain consistency.

- State Management: Terraform stores the state of the infrastructure in a separate backend, making it easier to share, manage, and collaborate on the same infrastructure across teams. AWS CloudFormation's state management is tied to the AWS account, which can lead to potential issues when sharing infrastructure across accounts or regions.

##### Consequences
While choosing Terraform brings numerous benefits for our new AWS project, there are some considerations to keep in mind:

- Additional Tool: With Terraform, we will have an additional tool in our tech stack, which may require some training for team members who are more familiar with AWS CloudFormation.

- Learning Curve: Although Terraform's learning curve is generally considered more accessible than AWS CloudFormation's, some team members may still require some time to get up to speed with Terraform's specific syntax and concepts.

- Terraform State Management: We need to ensure proper management and security of Terraform state files, as they contain sensitive information about the infrastructure.

ADRs and LADRs

It is essential to note that there is a difference between Architecture Decision Records (ADRs) and Lightweight Architecture Decision Records (LADRs).

ADRs are comprehensive documents that capture the context, reasoning, and impact of significant architectural decisions made during a software project. They provide a historical record and help stakeholders understand the thought process behind these decisions.

On the other hand, LADRs are a simplified version of ADRs, introduced by Thoughtworks. They aim to capture the essential information about an architectural decision without the need for extensive documentation. LADRs are concise and focus on the critical aspects of the decision, omitting less crucial details.

I have written an article explaining the difference between an Architectural Decision Record (ADR) and a Lightweight Architectural Decision Record (LADR).

You can read it here: https://medium.com/@canobertin/what-is-the-difference-between-an-architectural-decision-record-adr-and-a-lightweight-8d75971ea46b

The main difference between an ADR and a LADR lies in the level of detail and formality.

You can access the description and templates for both ADR and LADR at the following links:

ADR Template: https://github.com/joelparkerhenderson/architecture-decision-record

LADR Template: https://www.thoughtworks.com/en-us/radar/techniques/lightweight-architecture-decision-records

Where to Store Them

The most common approach is to use Markdown files stored in a version control system, like Git, which offers a lightweight and flexible way to document ADRs and LADRs.

By leveraging Markdown, developers can easily format and structure their ADRs, enhancing readability and accessibility. Storing them in version control allows for simple maintenance, review, and tracking alongside the codebase, ensuring they remain up-to-date and aligned with the project’s development process.

However you can use different file formats like plain text, Markdown, Word(.docx), or PDF. ADRs and LADRs can be stored in various places like Github, Sharepoint, or others.

Precautionary Steps for Navigating ADRs

ADRs can be both a blessing and a potential source of complexity for a project, depending on how they are handled. When done right, they can be a superhero, reducing complexity, and bringing clarity and order to the project. But, if not managed properly, they might sneak in some extra challenges.

Here are some things to keep in mind:

1. Document with Care: ADRs mean more documentation, which can be awesome for transparency. Just make sure to organize it well to avoid overwhelming everyone with paperwork.
2. Decisions, Decisions: Introducing ADRs means getting more formal with decision-making. It can be a bit daunting at first, but once everyone is on board, it’ll be smooth sailing.
3. Stay Up to Date: Like a favorite app, ADRs need regular updates. Keeping them current is crucial to avoid confusion and chaos.
4. Welcome Newbies: New team members might need a bit of time to get to know ADRs and how they work. Be patient and help them navigate this new territory.

ADRs in the Industry

ADRs have gained significant popularity in the software engineering industry. Many organizations and projects have recognized the value of documenting architectural decisions and have incorporated ADRs into their development processes.

Here is a list of Firms, Projects and People using them:

1. Spotify — They provide a comprehensive article explaining ADRs: Spotify ADR Article
2. UK Government — You can explore their AWS project implementation with ADRs in their GitHub repository: UK Government AWS Implementation
3. Decentraland — Check out their ADR repository to see how they manage architectural decisions: Decentraland ADR Repository
4. RedHat — Read their article on ADRs to get insights into how they use them: RedHat ADR Article
5. IEEE Magazine — This magazine has an article that covers ADRs in software development: IEEE Magazine ADR Article

Hey there! Thanks a bunch for stopping by and reading my medium post. I really hope you enjoyed this little guide and got something valuable out of it. I’m all ears for your feedback and any cool ideas you have for future topics! So feel free to drop me a line.

Keep smiling and stay awesome! :)