< Documentation

Decision records document the reasoning behind decisions. They help readers understand why a decision was made.

Decision record 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.''

== Decision-making process ==

''Describe the steps you took to evaluate the options, collect feedback, and make the decision.''

== Options considered ==

''Describe the options you considered in making the decision.''

== Decision ==

''Describe the decision you made and the rationale.''

== Consequences ==

''Describe the context after you apply the decision. Consequences may be positive, negative, or neutral.''

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/

Example

Example of a decision record

Decision record template v1

Author: User:APaskulin_(WMF)

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.

Wikimedia examples

References

This article is issued from Mediawiki. The text is licensed under Creative Commons - Attribution - Sharealike. Additional terms may apply for the media files.