Recording decisions so they survive turnover, and communicating architecture to mixed audiences.
3 questions in Architecture & Tech Leadership.
Stale documentation is a symptom of documenting things that change faster than anyone will maintain them. Write down decisions and their reasons, which are immutable once made, generate anything derivable from the code, and let the rest go undocumented on purpose.
An ADR captures the context that forced a choice, the options considered with the reason each was rejected, the decision, and the consequences including the costs you accept. Write one when the decision is expensive to reverse or would surprise a future reader, and supersede it rather than edit it.
Reconstruct the original context first and test whether it has genuinely changed or whether you simply inherited a cost you dislike, then write a new record that supersedes rather than edits the old one, price the half-reversed state explicitly, and get agreement from the teams who now carry the consequences.