Every time a new developer or architect joins the team, he or she have hundreds of questions concerning the system and its architecture. It is likely that some decisions made on the beginning of the project, still have its negative impact on team’s work. A newbie person who sees with a fresh pair of eyes, will quickly spot quirky aspects of the system. Now the question is — are you ready to give the comprehensive answers to all of them? If not, your project is probably missing Architecture Decision Records (ADR).
Explain The Decisions You Have Made
In simple words, ADR is there for the team to remember why a given decision was made. If you are sure, that functional or non-functional aspects of the system will change some day, then this is good to have an explanation why you did some things the way they are done. Imagine a programmer or architect, who will work on a Shopping Cart feature, which relies on Redis instead of SQl database like the rest of modules. Few employees know the story behind it, it was because Cart quickly became a bottleneck, because it is dependent on a few external services available through the network. To decrease amount of opened connections, all the external data was put into Redis key-value store for fast retrieval.
The problem is, that this new person had no idea why this particular solution was made using Redis, and decided to refactor it to use the SQL database, so it is consistent with the other components. What is even worse, it passed through a code review, because there was nobody to remember why Redis was used in a first place. The person behind this improvement moved to another company a few months back, so there was no one to inform the team why Cart is done the way it is. How the story ended? Well, users started reporting a huge performance drop when manipulating products in E-commerce system, what eventually led customers to move to another store.
When I Need An ADR?
If you think deeper about the decisions, you will quickly realise that everything what was done or used in the project has some decisions behind it. Programming language, naming conventions, architecture, infrastructure, you name it. Should it all be written as decision records? Well, not necessarily. If your company always uses PostgreSQL due to its JSON processing capacities, or Python programming language, because it is provided with tons of libraries, then answer is probably no. This is a knowledge, which is widely spread across the enterprise and everyone can answer it.
Situation becomes different, when decision was made after some discussions, where two or more parties were involved, bringing a fair portion of arguments to the table. Discussions could take place anywhere, it could be a meeting room, a dedicated chat on Slack or even a few kilometers long email thread. Just imagine how hard it would be to scroll these conversations, not to mention a face-to-face discussions, which are quickly forgotten. If this was the way for the decision to be made, then you should consider creating the Architecture Decision Record.
How ADR Should Be Stored?
ADR is a small document, usually a Markdown file. It contains explanations why a particular decision has been made, or describing issues, which are currently under discussion. Since ADR has a record in its name, it is not required to put it into a Markdown or any other file. It can be your internal Wiki or even issue tracking software, there are no strict guidelines how to keep those.
It is, of course, up to you and your team to decide what is the best form for these records, but there are generally some good and better ways to do it. Since they contain mostly the text, they are good candidates to keep them in version control. It is perfect if we can share our records with employees from other departments, they may provide some valuable input for us, so we can avoid mistakes or extra work.
Decision is a sum of all choices made over some particular topic. This is the thing of the past, so since we cannot time travel, it shouldn’t be edited, but rather a new version should be created. When ADR is overwritten, you are loosing its biggest advantage, which is a whole story behind that particular matter. Don’t rewrite the history, just append another chapters. Please, keep in mind that this is only my personal view on this matter, if you and your team want to keep everything in a single file, then this is fine with me, until it is fine with you. Tools are here to help and to make you feel comfortable. They are there for you, not the other way.
How I Should Structure My ADRs?
Another source of ADR-related info you can find on Joel Henderson’s GitHub repository. He is so nice, because he gathered everything in single place, and his proposals for conventions are widely accepted by the community. You can tell it by the number of starts and forks of his repo. Storing records in the repository is one of the ways to keep them within the project, so I will focus more on that. Don’t hesitate to check other ways Joel mentions.
Directory And File Naming For ADR
Directory proposed for keeping ADR files is simply adr in your project’s root folder. This is what I also prefer,
because in that form, it is easy and intuitive to find. When it comes to file naming convention, the one proposed by
Joel, is also my recommendation for you:
- file name uses kebab-case convention
- lowercase characters with dashes instead of spaces
- name of the file is the imperative verb in present tense:
- why-microservices.md
- choose-metrics-database.md
- choose-message-broker.md
Are There Any ADR Templates?
ADR is around for a while, so it seems obvious, that some templates have already been created. And this is true, there are few already, but once again I will focus on one invented by Michael Nygard. By the way, I love the way he talks about the documentation, about how rarely it is actually userful. In the end, docs die alone and forgotten. Anyway, let’s go through the file composition. It contains five sections, which must be filled.
Status
It is all up to you, but you can start with:
- PROPOSED: Waits for acceptance
- ACCEPTED: Development may start
- REJECTED: It wasn’t what company needed
- DEPRECATED: We don’t need this anymore
- SUPERSEDED: There is a new version in a separate file, which must be referenced
Title
This section tells the reason behind this ADR using short phrases:
- Why Microservices Architecture
- What Metrics Chosen For Database
- Why We Choose RabbitMQ over Kafka
Context
Good Context includes current state of business, its orientation and mission. You should put there as many details as you think might be helpful to provide answers to “whys”.
Decision
You have to describe what is the outcome. What you are going to do, what is the solution. What steps will you take to execute the decision.
Consequences
And here we are, the last, and the most important of them all. What will happen to us, after we develop and deploy our solution to production servers? Do we make a step forward, backward or our position remains the same? Is it going to cause any scalability problems? Will the system efficiency increase or decrease. And last, but not least, what about networking and volume of data send over it? Put all of it there, so other departments may be informed about your intentions, so it can be discussed and validated.
Summary
All the structures and rules above are battle-tested solutions, provided by some good people. They came up with some conventions, but remember, that you are free to adapt them to your team and your company. You can propose something completely different, if ideas will be distributed clearly and without noise. Do whatever is good for you.