Guideline: Documenting Architectural Decisions
This guideline describes the importance of documenting key architectural decisions, and factors to consider when doing so.
Relationships
Main Description

Before making any important decisions about the architecture, make sure that the process for making decisions has the right level of sponsorship necessary to enforce those decisions. Get agreement from affected parties on the decision making process.

When documenting an architectural decision, be sure to capture the issue addressed, and the actual decision made to resolve the issue. Include some discussion about the rationale behind the decision, the options considered, and the justification for choosing one option over another.

Review or consider one or more of the following when drawing up a list of alternatives:

  • Project objectives, goals, critical success factors, business drivers, and so on, that may have been provided by the stakeholders
  • The system requirements (business processes, use cases, qualities, constraints, and change cases)
  • Architectural principles, policies, and guidelines drawn up by the stakeholder
  • Relevant reference architectures, architectural patterns, or assets
  • Product literature available from vendors or their Web sites
  • Technical information published in books, journals, Web sites, and so on
  • Project documentation such as plans, key milestones and dates, and so on

Consider the following questions as part of the decision making process:

  • Does the solution need to comply with a reference architecture or architectural pattern?
  • Does the architecture need to comply with any overarching principles, policies, guidelines, or standards?
  • What are the systems management and support implications of the decision?
  • What are the security and privacy implications of the decision?
  • How does the decision affect the total cost of ownership?
  • If the decision requires the use of vendor products, packages, consulting, or support, what are its implications? For example, what is the experience of the vendor? Are there suitable service level agreements in place? Are there any liability or legal issues to address?
  • If the decision requires the use of a product or package, what is the lead time on procuring these? Is the time consistent with project timelines?
  • Are there any changes you need to take into account?

At a minimum, document decisions that affect the overall structure of the system, the partitioning and distribution of functionality, or the selection of a particular product, package, or asset. You should still document additional architectural decisions, but do so less formally (either as part of the overall architectural model, or by using only a subset of the information outlined here).

Ensure that the overall set of architectural decisions covers the full scope of the project. Decisions that focus on only a few areas may mean that insufficient architectural influence is exerted. The full set of decisions includes those items that require global coordination across the program. They should address the classic trade-off questions, such as those relating to performance, flexibility, extensibility, availability, and reliability.

Make architecturally significant decisions early; this is the key to a good architecture in that it sets the foundation on which the rest of the architecture is based. Test or prototype architectural decisions early. If necessary, reconsider them based on information gathered from these activities. You do not need to make all decisions at once: you can spread them out as the system evolves. For example, you might ignore the details of persistence early in the project provided that you have identified a component or mechanism that deals with persistence. Address high-risk architectural decisions first. High-risk areas are those for which there is little knowledge available, or that may involve untried technology.

Inform all affected parties about the decisions. Carry through and actually implement decisions, and track them to show evidence the decisions are enforced.