“Why Did They Do That?” Solving Architecture Mysteries with ADRs

We’ve all asked the question: “Why did they do it like that?” When architectural decisions aren’t documented, confusion, rework, and frustration are almost guaranteed. That’s where Architectural Decision Records (ADRs) come in—not as boring documentation, but as lightweight, practical tools that capture the why behind your system’s design.
In this session, you’ll discover why teams forget their own decisions (hint: memory isn’t version control), how to write clear, concise ADRs that people actually read, and real-world (sometimes funny) examples of what happens when ADRs are missing. You’ll also see how ADRs can save future developers—including future you—from unnecessary guesswork.
Walk away with a simple, effective approach to documenting decisions so the next time someone asks “What were they thinking?”, the answer is already written down.