davidaayers / adr-talk Goto Github PK

Presented by: David Ayers
Innovative Technology Professional | Passionate Lifelong Learner | Giant Nerd
Full Bio
@iamagiantnerd, [email protected]

As technologists, we make architectural decisions all of the time; what we're not good at is recording the context surrounding the decision and properly communicating that decision to the rest of the team (or teams). Enter ADRs (Architecural Decision Records) -- a lightweight was to record and communicate these decisions.

"Why did we decide this?" – every developer in history, 12 months after making a decision.

As technologists, we make architectural decisions all of the time. What we're not good at doing is:

• Socializing these decisions though the team/department (whoever participated in the discussion has the context, everyone else is out of luck!)
• Recording the decisions, and more importantly, the context behind the decisions, in a way that our future selves (or anyone – someone just joining the team, for example) can look back and understand why the decision was made and what the factors that went into the decision were.

Enter ADRs. First proposed by Michael Nygard, Architectural Decision Records provide a way to capture these decisions as part of the codebase that you're working on; where the rubber meets the road.

In this short lightning talk, we’ll go through the case for ADRs and a simple primer and how to get started using this technique in your projects.

The following links are referenced in the presentation:

• Original Blog Post about ADRs:
  • Michael Nygard: http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions
• Tools:
  • Command line ADR tool: https://github.com/npryce/adr-tools
  • Compendium of ADR information: https://adr.github.io/
• Real world examples of ADRs:
  • https://github.com/npryce/adr-tools/tree/master/doc/adr
  • https://github.com/arachne-framework/architecture
  • https://github.com/marc-bouvier/trello2eisenhower/tree/master/adr
  • https://github.com/hilton/scripting-docs/tree/master/ADR