Documentation/Decision records
Decision records document the reasoning behind decisions. Decision records help readers understand why a decision was made. You can use these templates as a starting point for adding decision records to a project. These templates do not replace the templates used as part of the technical decision-making process.
Decision record templates
[edit]Quickstart
[edit]To get started, here's a simple template that works for most decisions:
- Status
- Context
- Options considered
- Decision
- Consequences
| Wikitext template |
|---|
Location: Decision records/
Title: Short phrase describing the subject of the decision
Authors:
== Status ==
Proposed, accepted, superseded, deprecated, or any clear, accurate state. Include the date of the status change, and link to relevant discussions. Add new status changes as a list.
* [Status] on [YYYY-MM-DD]
== Context ==
Describe the forces that impact the decision. These forces may be technological, political, social, or informational. Note any tensions between these forces. Use value-neutral language in this section. Focus on describing facts.
== Options considered ==
Describe the options you considered in making the decision.
== Decision ==
Describe the decision you made and the rationale. Include any risks involved and how you plan to manage those risks.
== Consequences ==
Describe the context after you apply the decision, including effects on people and future work.
|
Complete
[edit]Here's a template you can use for decisions that are more complex:
- Summary
- Status
- Decision-making process
- Stakeholders
- Context and problem statement
- Risks and mitigations
- Options considered
- Decision
- Consequences
| Wikitext template |
|---|
Location: Decision records/
Title: Short phrase describing the subject of the decision
Authors:
[Provide a short summary of the decision]
== Status ==
Proposed, accepted, superseded, deprecated, or any clear, accurate state. Include the date of the status change, and link to relevant discussions. Add new status changes as a list.
* [Status] on [YYYY-MM-DD]
== Decision-making process ==
Describe the steps you took to evaluate the options, identify stakeholders, collect feedback, and make the decision.
== Stakeholders ==
List the people and groups you identified as stakeholders. If you have a list of roles and responsibilities, you can include it in this section.
== Context and problem statement==
Describe the forces that impact the decision, define the problem, and describe the constraints on the decision. Use value-neutral language in this section. Focus on describing facts.
== Risks and mitigations ==
Describe any risks posed by making the decision and how you plan to mitigate those risks.
== Options considered ==
Describe the options you considered in making the decision. Use descriptive subheadings, not just "option 1".
== Decision ==
Describe the decision you made and the rationale.
== Consequences ==
Describe the context after you apply the decision, including effects on people and future work.
|
| Phabricator template |
|---|
Title: Short phrase describing the subject of the decision
Authors:
[Provide a short summary of the decision]
## Status
Proposed, accepted, superseded, deprecated, or any clear, accurate state. Include the date of the status change, and link to relevant discussions. Add new status changes as a list.
* [Status] on [YYYY-MM-DD]
## Decision-making process
Describe the steps you took to evaluate the options, identify stakeholders, collect feedback, and make the decision.
## Stakeholders
List the people and groups you identified as stakeholders. If you have a list of roles and responsibilities, you can include it in this section.
## Context and problem statement
Describe the forces that impact the decision, define the problem, and describe the constraints on the decision. Use value-neutral language in this section. Focus on describing facts.
## Risks and mitigations
Describe any risks posed by making the decision and how you plan to mitigate those risks.
## Options considered
Describe the options you considered in making the decision. Use descriptive subheadings, not just "option 1".
## Decision
Describe the decision you made and the rationale.
## Consequences
Describe the context after you apply the decision, including effects on people and future work.
|
Where to publish decision records
[edit]The simplest way to publish decision records is all on a single page, in chronological order. If the page gets too long, you can split the decision records into separate pages.
If you use a separate page for each decision record, make sure you maintain a list of decision records in chronological order. For example, in MediaWiki, you can add the date to the title of each page (such as Decision records/2023-05-05 Subject of the decision and transclude a list of subpages using {{Special:PrefixIndex|prefix=}}.
You should publish decision records alongside other documentation used by project maintainers. For example:
- On a wiki at
[Project name]/Decision records/ - In a code repository at
docs/decision-records/
If the decision-making process happens on Phabricator, you can publish the decision record in the task description instead of on a wiki. If you publish decision records on Phabricator, it is still a good idea to maintain a list of significant decisions on a wiki page alongside other documentation used by project maintainers.
Example
[edit]| Example of a decision record |
|---|
Decision record template v1[edit]Author: User:APaskulin_(WMF) I decided to use a lightweight structure that captures the status, context, process, options, outcome, and consequences of a decision. Status[edit]
Context[edit]Decisions records are a generic version of architecture decision records, a lightweight type of documentation for recording decisions that have a significant impact on a codebase. Decision records can be useful for many types of decisions, not just those relating to software architecture. Although several Wikimedia Foundation teams maintain their own decision record template, there is no template recommended as part of the documentation resources on mediawiki.org. Decision making process[edit]To decide on a starting template for decision records, I researched popular structures for architecture decision records, proposed a draft, and then revised the draft based on feedback from KBach. Options considered[edit]There are several existing template for architecture decision records:
This is the most popular format I saw in my research. It's also the most minimalist. Variations I saw include moving Status to the beginning, making the context the lead section by removing the Context heading, and adding a Rationale section. Similar: pmerson/ADR-template, joelparkerhenderson/architecture-decision-record MADR ("Markdown Any Decision Records") "Long version":
"Short version":
The extra complexity in the heading adds confusion compared to the Nygard format, and the split into positive and negative consequences is overly prescriptive.
Not lightweight enough to be easily reusable.
This template is presented as a fill-in-the-blank sentence, so I've reinterpreted it as a structured document. I like that this template calls out constraints, but constraints could easily be combined with the Decision section. This template also uses a good/bad division for consequences, which I don't think is helpful. Decision[edit]A good decision record template should:
I decided to use a modified version of the Nygard and joelparkerhenderson template, breaking out the options considered and the process used from the Decision section. Single page vs one page[edit]I decided to prioritize ease of getting started and recommend a single page to start with, then recommend multiple pages if a single page becomes too cumbersome. Naming decision records[edit]The Nygard template recommends numbering ADRs. Numbering seems useful only in that it provides a chronology for the decisions. To be more clear, recommend naming decision records in separate files prefixed with the date in a sortable format. Documenting deciders[edit]To keep the process lightweight, don't require a specific way to document deciders, such as a responsibility assignment chart. Instead, add a section to document the decision making process, which is more open ended and can include deciders. Which decisions need to be documented?[edit]I decided not to recommend any kind of scope to avoid potential bikeshedding. Since decision records are not usually updated once they are written, extra decision records do not pose a documentation maintenance burden. Consequences[edit]There will be a reusable template for decision records available through Documentation that can be easily edited and iterated upon by people using decision records. |
Wikimedia examples
[edit]- Codex
- API Spec Reader
- Wikimedia Search Platform/Decision Records/Recommendation Flags in Search
- Wikimedia Product Infrastructure team/Push Notifications Infrastructure/Design Decisions
- Core Platform Team/Decisions Architecture Research Documentation/Dropping Abstract Schema Support For Oracle and MSSQL
- wikitech:Portal:Toolforge/Ongoing Efforts/Toolforge Build Service/Reports#Decision records
- wikitech:Wikimedia Cloud Services team/EnhancementProposals
- meta:Toolhub/Decision record