What are the best practices for documenting architecture trade-offs?

1 Use a standard template

A standard template can help you structure and organize your documentation of architecture trade-offs, as well as ensure consistency and completeness. You can use a template that is aligned with the architecture description standard (ISO/IEC/IEEE 42010), such as the Architecture Trade-off Analysis Method (ATAM) or the Quality Attribute Scenario (QAS) template. These templates typically include sections for describing the context, the stakeholders, the architecture drivers, the scenarios, the trade-offs, and the risks.

2 Focus on the key drivers

The key drivers are the requirements and constraints that have the most influence on the architecture decisions. They can be derived from the business goals, the user needs, the system environment, and the technical challenges. You should document the key drivers clearly and explicitly, and prioritize them according to their importance and urgency. You should also document how the architecture decisions address or satisfy the key drivers, and how they affect or compromise other drivers.

3 Use scenarios to illustrate trade-offs

Scenarios are concrete examples of how the system behaves or responds to certain events, stimuli, or conditions. They can help you demonstrate and evaluate the trade-offs between different architecture alternatives, as well as identify and mitigate the risks and uncertainties. You should document scenarios that cover both the normal and the exceptional cases, and that reflect the perspectives and concerns of different stakeholders. You should also document the expected outcomes, the quality attributes, and the metrics of each scenario.

4 Document the rationale and the assumptions

The rationale is the explanation of why you made a certain architecture decision, and what alternatives you considered and rejected. The assumptions are the facts or beliefs that you relied on when making the decision, and that may affect its validity or applicability. You should document both the rationale and the assumptions for each architecture decision, as well as the sources and evidence that support them. This can help you justify and defend your decisions, as well as review and revise them if the assumptions change or prove wrong.

6 Use tools and formats that facilitate collaboration

The documentation of architecture trade-offs is not only for your own reference, but also for sharing and communicating with other stakeholders, such as developers, testers, managers, customers, and users. You should use tools and formats that facilitate collaboration, such as wikis, diagrams, tables, charts, and matrices. You should also use clear and concise language, avoid jargon and acronyms, and provide glossaries and references. This can help you make the documentation accessible, understandable, and useful for different audiences.

7 Here’s what else to consider

This is a space to share examples, stories, or insights that don’t fit into any of the previous sections. What else would you like to add?