Difference between revisions of "ADRs, Guardrails and Golden Paths"
From CitconWiki
Jump to navigationJump to search (Created page with "...") |
|||
| Line 1: | Line 1: | ||
| − | ... | + | Architectural Decision Records (ADRs) |
| + | * [https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions Documenting Architecture Decisions] by Michael Nygard | ||
| + | * [https://martinfowler.com/articles/scaling-architecture-conversationally.html#adr 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. | ||
Revision as of 13:51, 4 February 2023
Architectural 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.
