ADRs, Guardrails and Golden Paths

From CitconWiki
Jump to navigationJump to search
The printable version is no longer supported and may have rendering errors. Please update your browser bookmarks and please use the default browser print function instead.

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
Retrieved from "http://citconf.com/wiki/index.php?title=ADRs,_Guardrails_and_Golden_Paths&oldid=16678"