Decisions for Software Design and Architectures
Decisions is the practice of documenting architecture so reasoning survives team changes. It uses architecture decision records for individual choices, lightweight diagrams for structure and living documents kept in version control, so future maintainers understand what was decided, which options were rejected and why.
Stage: Practice · Part of the Software Design and Architecture roadmap · Last reviewed 19 November 2026
What to learn in Decisions
- Write an architecture decision record with options and consequences
- Record a decision's status and link superseding records
- Diagram a system with C4 or a simple box-and-arrow view
- Keep documentation in the same repository as the code
- Decide what is worth documenting and what is noise
- Review old decisions when their assumptions change
Decisions interview questions
Why record rejected alternatives in a decision record?
They show what was considered and why it lost, which stops the team re-debating the same options and helps later readers judge whether the reasoning still holds when conditions change.
How do you keep architecture documentation from going stale?
Keep it small, store it beside the code, generate diagrams from source where possible, review it in pull requests, and document decisions and reasons rather than details that change often.
Where Decisions fits in the Software Design and Architecture roadmap
Decisions belongs to the Practice stage (advanced level). Decide and evolve.
Other units in this stage
Back to the full Software Design and Architecture roadmap