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](http://thinkrelevance.com/blog/2011/11/15/documenting-architecture-decisions), 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.

Additional Resources

About the Speaker(s)

No bio currently available.

Michael Keeling is a staff software engineer at LendingHome and the author of [Design It!: From Programmer to Software Architect](http://amzn.to/2ipIpme). Prior to LendingHome, he worked at IBM on the Watson Discovery Service. Michael has a Masters in Software Engineering from Carnegie Mellon University and a BS in Computer Science from the College of William and Mary. Michael has hosted popular and highly reviewed sessions at numerous agile conferences including XP and Agile. Michael is also a 3 time recipient of the SATURN/IEEE “Architecture in Practice” best presentation award in 2012, 2014, and 2018. A full list of his talks, workshops, panels, and papers are available on his website at http://www.neverletdown.net/p/speaking-and-writing.html