Agile2018 has ended
Back To Schedule
Wednesday, August 8 • 10:45 - 11:15
Share the Load: Distributing Design Authority with Lightweight Decision Records (Michael Keeling, Joe Runde)

Sign up or log in to save this to your schedule, view media, leave feedback and see who's attending!

Limited Capacity seats available

Documenting architecture design decisions is commonly considered a good practice but few teams take the time to write down the decisions they make. In our experience this happens for a few reasons: architecture documentation is rejected as being too heavyweight, documentation is typically out of sight and out of mind, and many developers don’t know what to document. Architecture Decision Records (ADRs), a lightweight documentation approach proposed by Michael Nygard, solves these problems by recording design decisions in a simple markdown template in the same repository as the code affected by the decision. We've found that this technique has many advantages. Documenting ADRs creates opportunities to involve more teammates in the design process. Up and coming architects can safely practice design under the guidance and review of experienced teammates. Over time ADRs form a catalog of proto-patterns that can be bootstrap future architectures.
In this talk we will share our experiences and lessons using ADRs over the past two years while working on the IBM Watson Discovery Service. By the end of this talk you will know how to create effective ADRs, introduce the technique to your team, and avoid common pitfalls with the method.
View the Experience Report

Lessons Learned from Your Experience:
  • How to phrase a decision as a lightweight decision record and share it with others
  • How to think through decisions and how to guide others in doing so
  • ADRs help us write better code
  • ADRs help us understand what risks we are accepting and we are able to think more strategically about risk
  • Other documentation is still required and ADRs are a good way to figure out what else needs to be documented. ADRs are a part of a minimalist set of design documentation
  • We can learn from past decisions in other parts of the system and extract team and institutional patterns


avatar for Michael Keeling

Michael Keeling

Staff Software Engineer, LendingHome
Michael Keeling is a software engineer at LendingHome and the author of Design It!: From Programmer to Software Architect. Prior to LendingHome, he worked at IBM on the Watson Discovery Service. Keeling has a Master of Science in Software Engineering from Carnegie Mellon University and a Bachelor of Science in Computer Science from the College of William and Mary... Read More →
avatar for Joe Runde

Joe Runde

Joe Runde is a software engineer who recently started his career at IBM. There he works on Watson while teaching about machine learning methods and learning about software design from many smarter folks. Joe has an MS in Machine Learning from Carnegie Mellon University and a BS in... Read More →

Wednesday August 8, 2018 10:45 - 11:15 PDT
Torrey Pines Room 1, 2, & 3