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. To enable project teams to easily use decision records in their documentation, publish a tool-agnostic template and set of best practices for decision records.
Draft: https://www.mediawiki.org/wiki/User:APaskulin_(WMF)/Decision_records
## Research (in the form of a decision record)
### Status
- Started draft in T338835 on 2023-06-13
### 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 teams maintain their own decision record template, there is no template recommended as part of the [documentation resources on mediawiki.org](https://www.mediawiki.org/wiki/Documentation).
### Decision
A good decision record template should:
- have clear headings with obvious meanings
- be lightweight
- allow for flexibility
There are several existing template for architecture decision records:
**[Nygard](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions)**
- 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](https://github.com/pmerson/ADR-template/blob/master/ADR-template.md), [joelparkerhenderson/architecture-decision-record](https://github.com/joelparkerhenderson/architecture-decision-record/blob/main/templates/decision-record-template-by-michael-nygard/index.md)//
**[MADR](https://adr.github.io/madr/examples.html)** ("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](https://personal.utdallas.edu/~chung/SA/zz-Impreso-architecture_decisions-tyree-05.pdf)**
- 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](https://ozimmer.ch/practices/2020/04/27/ArchitectureDecisionMaking.html)**
- 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.//
## Open questions
- Single page vs one page
- Best practices for naming decision records
- Documenting deciders
- Which decisions need to be documented? Scoping decision records (ADRs)
## Wikimedia examples
- https://doc.wikimedia.org/codex/latest/using-codex/adrs/overview.html
- https://gitlab.wikimedia.org/toolforge-repos/api-spec-reader/-/blob/main/docs/en/decision-records.md
- https://www.mediawiki.org/wiki/Architecture_decision_record_template
- https://www.mediawiki.org/wiki/Wikimedia_Search_Platform/Decision_Records/Recommendation_Flags_in_Search
- https://www.mediawiki.org/wiki/File:Decision_Record_TEMPLATE_pdf.pdf
- https://wikitech.wikimedia.org/wiki/Wikimedia_Cloud_Services_team/EnhancementProposals/Decision_record_template
- https://wikitech.wikimedia.org/wiki/Wikimedia_Cloud_Services_team/EnhancementProposals
- https://www.mediawiki.org/wiki/Wikimedia_Product_Infrastructure_team/Push_Notifications_Infrastructure/Design_Decisions
- https://www.mediawiki.org/wiki/Core_Platform_Team/Decisions_Architecture_Research_Documentation/Dropping_Abstract_Schema_Support_For_Oracle_and_MSSQL
- https://wikitech.wikimedia.org/wiki/Portal:Toolforge/Ongoing_Efforts/Toolforge_Build_Service/Reports#Decision_records
- https://meta.wikimedia.org/wiki/Toolhub/Decision_record
## References
- https://en.wikipedia.org/wiki/Architectural_decision#Decision_documentation
- https://adr.github.io/
- https://github.com/joelparkerhenderson/architecture-decision-record
- https://saturn2017.sched.com/event/9k2y/architecture-decision-records-in-action