Difference between revisions of "ADRs, Guardrails and Golden Paths"
From CitconWiki
Jump to navigationJump to search (Created page with "...") |
|||
| (One intermediate revision by the same user not shown) | |||
| 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 | ||
| + | * They could certainly act as an aid when outsourcing a project especially when there is the possibility of the code and maintenance coming back to you at some point. | ||
| + | |||
| + | 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. | ||
| + | |||
| + | Golden Paths | ||
| + | * The 3rd type of document I've been promoting is a Golden Path or well-documented, potentially with tooling support, but repeatable path for a specific implementation. | ||
| + | * [https://engineering.atspotify.com/2020/08/how-we-use-golden-paths-to-solve-fragmentation-in-our-software-ecosystem/ Golden Paths at Spotify] | ||
| + | ** Aside: there is a system available from Spotify for managing a related developer portal for golden paths: [https://backstage.spotify.com/ Backstage] | ||
| + | * AKA [https://netflixtechblog.com/how-we-build-code-at-netflix-c5d9bd727f15 Paved Roads at Netflix] | ||
Latest revision as of 14:58, 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
- They could certainly act as an aid when outsourcing a project especially when there is the possibility of the code and maintenance coming back to you at some point.
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.
Golden Paths
- The 3rd type of document I've been promoting is a Golden Path or well-documented, potentially with tooling support, but repeatable path for a specific implementation.
- Golden Paths at Spotify
- Aside: there is a system available from Spotify for managing a related developer portal for golden paths: Backstage
- AKA Paved Roads at Netflix
