Architectural Decision Records
The typical ADR consists of:
| Components | Comment |
|---|---|
| Problem Statement | The problem statement that drove the need for an ADR |
| Current Status | Draft, approved, declined, etc. Some ADRs will be abandon for other approaches or changes in direction. |
| Alternatives | The viable alternatives that were considered and their pros and cons. |
| Decision | The chosen solution including enough information to give direction to those that did not participate in the discussion. |
| Impact and implications | Side effects, technical, staff, training, customer |
| Related decisions, other ADRs | Cascading decisions or impacts on previous work. |
| Context Diagrams | Most people are visual thinkers. Include context diagrams where they can help someone in the future. |
In some environments, ADRs also capture some RACI matrix actors:
| Role | Description |
|---|---|
| Responsible | The person or persons who raised the issue or created the ADR |
| Accountable | The person who had to approve the decision, often the lead |
| Consulted | Team members and partner team members |
| Informed | People or teams that were impacted or were notified. |
ADRs can be used for technical and non-technical decisions as shown in some of the links below.
They are not
An ADR is not intended to defend a decision or act as a shield against criticism. It exists to provide information for the initial implementation and to provide context for additional work in the future.
Who Benefits?
ADRs offer significant benefits over ephemeral channels like conference calls, email, and team channels. The decision lives beyond the shelf life of the media or the tenure of individuals on the team.
Future You: They aid you in future discussions when making decisions that sit on top of the ADR. You can go back and remember any subtleties or risk areas in that space.
Current and future peers and team members: ADRs make the decision process and results available to other team members and to new team members that join the group down the road. ADRs can reduce the amount of 1:1 knowledge transfer required when onboarding new teams or partners.
Ownership Changes: Projects and programs often change ownership during corporate reshuffling or reorganization. ADRs can provide a foundation for how something is structured and why. It also helps the new owners avoid the "why did they do it this way" trap.
How should they be stored?
ADRs are simple. The storage format should be simple, long lastable, and easily indexed by search engines. The documents should be stored where they can be found and where their lifecycle matches the lifecycle of anything built from the ADR.
| Purpose | Location | Format |
|---|---|---|
| Software design, SDLC, code organization | In the source tree. Git has standardized locatons | Universally editable format like Markdown. See sample Markdown templates below. |
| Departmental or enterprise architecture level ADRs | Internal Wikis | wiki markup |
| Program or enterprise-level ADRs | Sharepoint-style sites. | native format |
ADR Templates and other articles
Video
Created 2021 06 29
Comments
Post a Comment