Have You Gone MADR?
summary
Argues for storing decision records as Markdown files next to source code, showing a live repo example (open source library) that documents the chosen Java version and why alternatives like extra dependencies or Lombok were rejected; recommends one-page ADRs in the repo, use the MADR template variants (minimal vs full), keep ADR commits and merge requests focused, mark superseded records rather than editing them, and notes tooling support: IntelliJ, Maven builds, and Java 23 markdown in Javadoc plus sensible human review (not blindly trusting AI).
AI-written summary · about
chapters (14)
- 0:00Introduction and speaker intro
- 1:17Why document decisions
- 3:07Introducing MADR and its benefits
- 5:56How to write effective ADRs
- 7:23Live demo of creating an ADR
- 10:16Team adoption and review process
- 11:43Starting with ADRs in your team
- 13:28Markdown in Java and AI benefits
- 15:56Markdown documentation advantages
- 17:43Team-specific ADR practices
- 18:37Q&A on superseding decisions
- 21:09Q&A on AI and ADR maintenance
- 22:31Q&A on permanent proposed ADRs
- 23:14Closing and feedback request
related talks
54mHow'd we get here? A guide to Architectural Decision Records
43mGetting Started with Architectural Decision Records
42mIntroduction to ADRs
47mMaking architecture decisions, the Agile Way
43mWorking Efficiently with Architecture Decision Records (ADRs)
14mArchitecture Decision Records
27mJudging ‘It’s About Balance’ — The Path to Technical Excellence Through ADR Practice
39mOne Does Not Simply Make Architecture Decisions Alone: ADRs and Architec