Software Engineering Institute | Carnegie Mellon University
Software Engineering Institute | Carnegie Mellon University

Digital Library

Javascript is currently disabled for your browser. For an optimal search experience, please enable javascript.

Advanced Search

Basic Search

Content Type


Publication Date


Architecture Decision Records in Action

  • May 2017
  • By Michael Keeling (IBM Watson Group), Joe Runde (IBM)
  • Architecture Decision Records capture architectural design decisions in a lightweight plain-text template stored in your existing version control system.
  • Publisher: Software Engineering Institute
  • This presentation was created for a conference series or symposium and does not necessarily reflect the positions and views of the Software Engineering Institute.
  • Abstract

    Documenting architecture design decisions is commonly considered a good practice, but few teams take the time to write down the decisions they make. 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 ADR. In this talk, we will share our experiences and lessons from using ADRs over the past year while working on multiple projects for IBM Watson. By the end of this talk, you will be able to create effective ADRs, introduce them to your team, and avoid common pitfalls with the method.

  • Download

Part of a Collection

SATURN 2017 Presentations