In a recent episode of Technology Radar from Thoughtworks there was a mention of Design system decision records.
What is that?
An Architecture Decision Record is a text file that is created to describe a specific architectural decision. I use .md files and store them in Git. There are other tools and formats, such as a page on your company's wiki. The file should be concise, and contain the sections I'll talk about below.
Why do we need that?
ADRs are a way of documenting architectural decisions and their reasoning. They provide a historical record of important decisions and help teams understand why a particular approach was chosen. An ADR should be created by the team responsible for making the architectural decision. They should include information such as the problem being solved, the alternatives considered, the decision made, and the reasoning behind it. They are immutable documents. When a given decision is revisited, it typically results in a new document being created. ADR practice is becoming increasingly popular, so major cloud providers such as AWS and GCP added it to their respective documentation.
How to manage these records?
Here is an example of structure of logs. And in that thread from mastodon practical advice on adopting it at team.
My gist with template which I practice at my work: https://gist.github.com/DmytroLitvinov/8cae5975248ad43e12012e05cad78432
Helpful links:
- https://mastodon.social/@kevlin/109517740925744193
- https://docs.aws.amazon.com/prescriptive-guidance/latest/architectural-decision-records/appendix.html
- https://zeroheight.com/blog/capturing-your-design-system-decisions/
- https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions
- https://github.com/joelparkerhenderson/architecture-decision-record