Overview

I researched Architecture Decision Records (ADR).

What is ADR?

A document that records architectural decisions, introduced by Michael Nygard in 2011. cf. cognitect.com - DOCUMENTING ARCHITECTURE DECISIONS

Format

The format proposed by Michael Nygard is as follows: cf. cognitect.com - DOCUMENTING ARCHITECTURE DECISIONS

• Title
• Context
  • The context. What scene the decision is made in.
• Decision
  • It is recommended to have one decision per ADR.
• Status
  • Proposed, Approved, Deprecated, etc.
• Result
  • An explanation of the state after applying the decision, including the context of the results.

The document should be a readable length of about 1-2 pages.

Advantages of Adopting ADR

• Easier to catch up on design decisions regarding architecture.
• Reduced frequency of discussions about explicitly stated decisions.
• Contributes to transparency of architecture within and outside the team.

Criteria for Deciding Whether to Adopt ADR

• Is it something that the team repeatedly discusses?
• Is it a decision regarding design made by the team?
• Is it a decision that affects the entire software?

Whenever making some architectural judgment or decision, there will be opportunities to write an ADR.

Thoughts

• In Fundamentals of Software Architecture,
• When considering introducing ADR, it seems good to first write an ADR about the introduction of ADR itself.
• It felt that managing ADRs alongside source code in a repository is preferred, differing slightly from Design Docs.
• I thought it would be good to keep the criteria for deciding whether to write an ADR simple.
  • Write everything that was discussed and decided by the team, etc.
• Searchability of ADRs
  • It might be good to have proper searchability when wanting to search ADRs operationally (if the number becomes large).
  • It seems better to categorize and tag them thoughtfully.

References

• github.com - Architecture decision record (ADR)
• cognitect.com - DOCUMENTING ARCHITECTURE DECISIONS
• docs.aws.amazon.com - ADR process
• betterprogramming.pub - The Ultimate Guide to Architectural Decision Records Introduction
• engineering.atspotify.com - When Should I Write an Architecture Decision Record
• www.redhat.com - Why you should be using architecture decision records to document your project
• www.thoughtworks.com - Lightweight Architecture Decision Records
• developer.mamezou-tech.com - Recommendation for Architecture Decision Records
• cloud.google.com - Overview of Architecture Decision Records
• qiita.com - Record the "Why?" of Architecture! What is ADR?
• qiita.com - How to Document Architecture - ADR and ARCHITECTURE.md Template
• blog.studysapuri.jp - Record that Decision - Using Architecture Decision Records (ADR)
• fintan.jp - Case Study of Introducing Architecture Decision Records