Architecture Decision Records

because communicated decisions are
easier to understand and change   

Why document architecture decisions?

Prevent knowledge loss - why did a developer (that might not be working on the project) decide on a certain stategy?
Make more conscious decisions - easier to discuss and review strategies
Partial onboarding - contextualize developers on what matters for their tasks only

Particularly relevant for legacy systems.

• Why did someone choose typescript over javascript, then went back on that decision?
• Why didn't the developer implement a bundling strategy for SOME scripts only?
• Why do we have project asset folders with different names?
• Why are there commits that follow a specific structure, and others that don't? 
• Why did we pick bootstrap-datetimepicker over other datepicker plugins?

Why ADRs?

• Simple template
• Industry standard
• Never outdated
• Optional tooling 

What it is?

"a collection of records for "architecturally significant" decisions: those that affect the structure, non-functional characteristics, dependencies, interfaces, or construction techniques." - http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions

What does ADR look like?

1. Title
   1. date
2. Status - accepted | rejected | pending
3. Context
4. Decision
5. Consequences

ADR Examples

• https://github.com/npryce/adr-tools/blob/master/doc/adr/0004-markdown-format.md

Tooling

• https://github.com/npryce/adr-tools/blob/master/INSTALL.md

Bibliography

• https://understandlegacycode.com/blog/earn-maintainers-esteem-with-adrs/
• https://github.com/joelparkerhenderson/architecture_decision_record