Difference between revisions of "ADRs, Guardrails and Golden Paths"
From CitconWiki
Jump to navigationJump to search| Line 10: | Line 10: | ||
** I have seen many cases of making general blanket architecture decisions (or suggestions) and labeling them as ADRs | ** 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 | * 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 | 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). | * 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. | * 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 13: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
