True agile projects follow an emergent architecture, changing both functional and non-functional requirements along its entire lifecycle. Those changes require decisions 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 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 to reach a decision 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.