Heuristics

Write Down Decisions Early and Often

Authors: Andrea Magnorsky, Kenny Baas-Schwegler

Submitter: Kenny Baas-Schwegler

When and how should teams document their architectural decisions?

Context

Rather than writing a decision record after a decision has already been made, which can feel bureaucratic and less useful, teams should start the document early in the decision-making process. This makes the process more useful and collaborative. The ADR should capture not just the final choice but also the options considered and the rationale behind each. This approach turns the ADR from a simple record into a "writing as thinking" tool.

Examples

When a team is trying to decide on a new database, they start a decision record document right away. They document the problem, the options they are considering (e.g., PostgreSQL, MongoDB, etc.), the pros and cons of each, and any conversations or opinions from different people. This living document evolves with the discussion, making the entire process transparent and explicit.

Tags

Follow us

Read our latest news from Virtual DDD on any of these social networks!

Recent heuristics

Discussed content

The Reality of Systems Change: Facilitating Architecture with Transparency