Work Product (Artifact): Architectural Decisions
Documents key decisions about the architecture and the rationale behind those decisions.
Purpose

The purpose of this artifact is to:

  • Ensure there is a single, authoritative source for communicating key decisions made about the architecture
  • Record the rationale and reasoning behind each decision
  • Maintain the overall architectural integrity of the solution by ensuring all decisions are consistent with each other
  • Ensure the same issues are not addressed more than once because the resolution was forgotten
Relationships
RolesResponsible: Modified By:
Input ToMandatory: Optional:
  • None
External:
  • None
Output From
Description
Main Description

This artifact documents key architectural decisions and the rationale behind those decisions.

Brief Outline

The Architectural Decisions artifact contains the following sections: 
 

  • Summary and Status - summarizes all decisions and their status
  • Architecturally Significant Requirements - lists requirements that must be implemented to realize the architecture
  • Architectural Constraints - lists any constraints on the way developers must build the system
  • Reusable Assets - lists any potentially reusable assets; notes whether each asset is to be used as-is, enhanced, or not used; cites reasons for each decision
  • Architectural Mechanisms - lists the architectural mechanisms and describes the current state of each one
  • General Findings and Recommendations - lists any other decisions

Capture the following information for each architectural decision:

  • Problem - What is being decided or the issue that is being addressed.
  • Assumptions - What is believed to be true about the context of the problem.
  • Motivation - Why this decision is important.
  • Alternatives - A list of options considered and explanations.
  • Decision - The decision taken, possibly with references to related artifacts.
  • Justification - Why the decision was made together with reference to any supporting principles and explanations of deviations from compliance.
Properties
Optional
Planned
Key Considerations

Some important considerations for making and implementing architectural decisions:

  • Make sure the process for making decisions has the right level of sponsorship necessary to enforce those decisions
  • Make architecturally significant decisions early and be sure to validate high risk decisions using an executable architecture
  • Review and update architectural decisions as development progresses and update this artifact so it reflects any changes to your decisions
  • It is not necessary to document every minute decision you make when developing the architecture; focus on those that are controversial or are based on reasoning that is not obvious
Tailoring
Impact of not having

If architectural decisions are not recorded, one or more of the following problems may arise:

  • Different parties may make decisions more than once, and the decision may be different each time
  • You may have difficulty getting closure on controversial decisions due to unclear rationale
  • Decisions may be inconsistent or contradict other decisions
  • New people on the project may take longer to understand the architecture
Reasons for not needing

When an architecture is under development, there are virtually no reasons not to record architectural decisions. This artifact is not needed if the decisions have been captured elsewhere, but be sure you have captured the additional information such as rationale and options considered.

Representation Options

You may simply document Architectural Decisions as free format text with headings like problem, alternatives, resolution, and justification. A tabular format in a document or spreadsheet is an effective way to organize Architectural Decisions. A more sophisticated option is to use databases, collaboration tools, or requirements management tools.

More Information
Checklists
Estimation Considerations