True agile projects follow an emergent architecture, changing both functional and non-functional requirements along its entire lifecycle. Those changes require decision-making and updates to its backing material.

Documentation is good, yet long-winded wikis or multi-paged documents are hardly maintained, let alone read. Even worse if those decisions are stored as slide decks. Those are wasteful forms of information dumping that don’t pay off.

In 2011 Michael Nygard shared the idea of creating architecture decision records (ADRs): plain-text, independent markdown files with key topics. Those files contains all the context needed for the decision-making process and the consequences of it. They’re then versioned and stored the same way as code.

ADRs allows tracking historical reasoning in a clean and concise way.

You can find the original template and scripts from Nygard plus variations in the community-driven ADR GitHub organization. I personally like the MADR template due to its short questions that reminds you of important content to fill in.