ADRs, Guardrails and Golden Paths
From CitconWiki
Jump to navigationJump to searchArchitectural Decision Records (ADRs)
- Documenting Architecture Decisions by Michael Nygard
- Scaling the Practice of Architecture, Conversationally
- There's also a great ADR template in there.
- ADRs need to be documented at the time the decision is made
- Include the reasoning behind why the decision was made at the time
- A lot of recommendations are to author in markdown and check in to version control
- I think it should live in the repo for which the decision applies
- Problems
- I have seen many cases of making general blanket architecture decisions (or suggestions) and labeling them as ADRs
- Encourage people to author ADRs as an opportunity towards career growth
Guardrails
- Another type of documentation I've been promoting are "guardrails" which are constraints that are put in place by some central team (e.g. CTO, Security team, etc).
- These are not ADRs in that they are general constraints that all architectures of the org are expected to be adhered to.