Decisions in building microservices software

When it comes to building software, decisions are a big deal. Professional software engineers and architects get paid a lot for the decisions that they make and the prob‐ lems they solve. The quality of the software and the business outcomes they drive depend on the quality of those decisions.

But decisions aren’t always easy to make. They also aren’t always correct. We make the best decisions we can given the information, experience, and talent that we have. When any of those variables change, our decisions should change too. Some decisions are correct at the time but become outdated when technology, people, or situations change. Some decisions were never good ones in the first place. In either case, we need a way of capturing the decisions that matter so we can re-evaluate and improve on them over time.

To address that need, we’re going to use a tool called an architecture decision record (or ADR). We’re not sure who invented the term ADR or when it was first used, but the idea of documenting design decisions has been around for a long time. The real problem is that most people don’t take the time to do it. In our experience, ADRs are an extremely useful tool and a good way of getting clarity on the decisions that need to be made.

A good decision record needs to capture four important elements:

Context

What is the challenge? What is the problem that we are trying to solve? What are the constraints? A decision record should give us a summary of these contextual elements. That way we can understand the rationale for a decision and why it may need to be updated.

Alternatives

A decision isn’t a decision unless there is a choice to be made. A good decision record should help us to understand what the choices are. This helps us to better understand the context and the “selection space” at the time the decision was made.

Choice

At the heart of a decision is the choice. Every decision record needs to document the choice that was made.

Impact

Decisions have consequences and a decision record should document the important ones. What are the trade-offs? How will our decision choice impact the way we work or other decisions that need to be made?

You can create decision records however you like. You can write them up as text files, use a project management tool, or even track them in a spreadsheet. The format and tooling are less important than the content. As long as you capture the areas we’ve described you’ll have a good decision record.

For our example project, we’ll use an existing format called a lightweight architectural decision record (LADR). The LADR format was created by Michael Nygard and is a nice concise way of documenting a decision record. Let’s get to know LADR by building one together.

Writing a Lightweight Architectural Decision Record

The first key decision we’ll record is the decision to keep a record of decisions. Put more simply, we’ll create an ADR that says we intend to keep track of our decisions. As we’ve mentioned, we’ll be using the LADR format. The nice thing about LADR is that it’s designed to be lightweight. It lets us keep track of decisions in simple text files that we can write quickly. Since we’re dealing with text files, we can even manage our decision records in the same way we manage source code.

LADRs are written using a text format called Markdown, which provides an elegant and simple way of writing documentation. What’s great about Markdown is that it’s easy for humans to read in its raw form and most popular tools know how to render it. For example, Confluence, GitLab, GitHub, and SharePoint can all process Markdown and present it as a formatted, human-readable document.

To create our first Markdown-based LADR, open your favorite text editor and start working on a new document. The first thing we’ll do is lay out the structure.

Add the following text to your LADR file:

# OPM1: Use ADRS for decision tracking

## Status Accepted

## Context

## Decision

## Consequences

These are the key elements of our decision record. The # characters preceding the lines are Markdown tokens that will let the parser know that these lines are meant to be headings. Notice that we’ve given this decision a title that corresponds to the decision we’re making. We’ve also given the decision the slightly cryptic title: “OPM1.” This is just a short form code that will help us label and understand which part of the system the decision relates to. In this case, “OPM1” indicates that this is the first decision we’re recording related to the operating model.

The Status header of our record lets us know what life-cycle stage this decision is in. For example, if you’re drafting a new decision that you need to get an agreement on, you might start with a status of Proposed. Or, if you’re considering changing an existing decision, you might change its status to Under Review. In our case, we’ve already made the decision for you, so we’ve set the status to Accepted.

The Context section describes the problem, constraints, and background for the decision being made. In our case, we want to capture the need to log important decisions and why that’s important. Add the following text (or your own variation of it) to the Context section of your record:

## Context

Microservices architecture is complex and we’ll need to make many decisions. We’ll need a way to keep track of the important decision we make so that we can revisit and re-evaluate them in the future. We’d prefer to use a lightweight, text-based solution so that we don’t have to install any new software tools.

With the context in place, we can move on to recording the actual decision we’ve made. We can list some of the alternatives considered as well as our choice to use LADR. Add the following to the Decision section to document this fact:

## Decision

We’ve decided to use Michael Nygard’s lightweight architectural decision record (LADR) format. LADR is text based and is lightweight enough to meet our needs. We’ll keep each LADR record in its own text file and manage the files like code.

We also considered the following alternative solutions:

Project management tooling (not selected, because we didn’t want to install tools) * Informal or “word of mouth” record keeping (not reliable)

All that’s left is to document the consequences. In our case, one of the key consequences is that we’ll need to spend time actually documenting our decisions and managing the records. Let’s capture that as follows:

## Consequences

We’ll need to write decision records for key decisions

* We’ll need a source code management solution to manage decision record files

That’s all it takes to write a LADR. This is an incredibly useful way of capturing your thinking and has the added benefit of forcing you to make rational, thoughtful decisions in the first place. As we build our example flights application, we’ll be keeping a log of the key decisions we make. To save time, we won’t write out the entire decision record. Instead, we’ll highlight that a key decision has been made as in the following note.

If you want to use something other than LADR, Joel Parker Hen‐ derson maintains a great list of ADR formats and templates.

You’ll be able to find a detailed version of each decision record at this book’s GitHub repository.

This was part of my knowledge of reading Book Microservices up and Running.