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

Quickstart

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

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

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

Example of a decision record

Decision record template v1

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

Started draft in T338835 on 2023-06-13
Revised based on discussion with KBach on 2023-06-22
Published to Documentation/Decision records on 2032-06-26

Context

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

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

There are several existing template for architecture decision records:

Nygard

Context
Decision
Status
Consequences

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":

Content and problem statement
Considered options
Decision outcome
- Positive consequences
- Negative consequences
Pros and cons of the options
- Option 1 description
- ...
More information

"Short version":

Context and problem statement
Considered options
Decision outcome

The extra complexity in the heading adds confusion compared to the Nygard format, and the split into positive and negative consequences is overly prescriptive.

Tyree and Akerman

Issue
Decision
Status
Group
Assumptions
Constraints
Positions
Argument
Implications
Related decisions
Related requirements
Related artifacts
Related principles
Notes

Not lightweight enough to be easily reusable.

Y-statements

Context
Constraints
Decision
Alternatives
Benefits
Drawbacks

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

A good decision record template should:

have clear headings with obvious meanings
be lightweight
allow for flexibility

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

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

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

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?

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

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.