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.

Quickstart
To get started, here's a simple template that works for most decisions:


 * Status
 * Context
 * Options considered
 * Decision
 * Consequences

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

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  and transclude a list of subpages using.

You should publish decision records alongside other documentation used by project maintainers. For example:


 * On a wiki at
 * In a code repository at

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.

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
 * 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.

Wikimedia examples

 * 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
 * Wikimedia Cloud Services team/EnhancementProposals
 * Toolhub/Decision record