Trade-off Matrices
Document the options you considered and why you chose one over others. Trade-off matrices show that alternatives were evaluated and make your reasoning transparent to reviewers.
Architecture decisions involve choosing between alternatives. A trade-off matrix captures the options you considered, what you evaluated, and why you selected one approach over others.
The Trade-off Matrix Block
A dedicated block type for trade-off analysis lets you compare multiple options across consistent criteria.
This example uses the NeoArc Trade-off Matrix content block.
When to Use Trade-off Matrices
Not every decision needs a formal trade-off analysis. Use matrices for decisions that are:
Small, easily reversible decisions do not need this level of documentation.
Structuring Options
Each option in a trade-off matrix should include:
This example uses the NeoArc Trade-off Matrix content block.
Decision Status
Trade-off matrices track their lifecycle through status:
Status helps readers understand whether the matrix represents current guidance or historical context.
The Rationale Field
The rationale field explains why the preferred option was selected. This is often the most valuable part of the matrix.
Connecting to Constraints and Principles
Trade-off matrices often reflect constraints and principles documented elsewhere. A database decision might reference a data residency constraint. A deployment strategy might align with a reliability principle.
Make these connections explicit. When readers see that PostgreSQL was chosen partly because "all databases must support encryption at rest" (a documented constraint), the decision makes more sense.
This example uses the NeoArc Trade-off Matrix content block.
Adding a Trade-off Matrix
The matrices you see in this documentation were created using the same editor you will use for your own decisions.
Common Trade-off Categories
Architecture teams commonly document trade-offs for:
Revisiting Decisions
Trade-off matrices are not permanent. Circumstances change: new options become available, team skills evolve, requirements shift. Periodically review significant decisions to check whether the original rationale still holds.
When revisiting a decision, create a new matrix with updated options and current context. Keep the old matrix with status "deprecated" so the history remains visible.