MediaWiki

Data Platform Engineering/Technical Decision Record

< Data Platform Engineering

The Data Platform Engineering team has adopted the following technical decision record template. The technical decision record, often referred to as the architecture decision record (ADR), is a way to evaluate and document a significant decision and its consequences given a particular context and evaluation criteria.  

Why

edit

The technical decision template:

  • Facilitate a thorough decision making process, taking into consideration identified factors
  • Provide a way to identify all the parties that may be affected by a decision
  • Facilitate gathering feedback
  • Provide a historical record of decisions made

When

edit

General guideline for when to go through the TDR process include decisions that:

  • Involves choosing a new technology
  • Impact multiple systems and teams
  • Result in significant investment of time and resources
  • Not easy to reverse
  • Includes conducting POCs

Decisions that are narrower in scope can be documented within a Phabricator ticket or a design document. However any decision with multiple factors to consider would benefit from the provided format.

The technical decision record should be written before the work commences.

Who

edit

The TDR format allows anyone in the team to author the decision record. The tech lead(s) of the affected team(s) are usually the ones driving  the decision. The EM(s) of the affected team would be the ones to sign off on the decision.

Where

edit
  • Google Drive for initial draft to gather comments and asynchronously collaborate
  • Publish on Wiki
  • A link to the TDR should be entered into the Decision Log

***************************************************************************************************************

TDR Template

[short title of solved problem and solution]

edit
  • Status: [proposed | rejected | accepted | deprecated | … | superseded by ADR-0005]
  • Author: [author]
  • Deciders: [tech lead and team(s) responsible for decision]
  • Consulted:  [list of individuals and representative teams consulted]
  • Informed:[list of individuals who should be informed]
  • Date authored: [YYYY-MM-DD when the decision was created]
  • Date decided: [YYYY-MM-DD when the decision was finalized]

Technical Story: [description | ticket/issue URL]

Keywords

edit

List of keywords to assist in finding relevant TDRs

Context and Problem Statement

edit

[Describe the context and problem statement, e.g., in free form using two to three sentences. You may want to articulate the problem in the form of a question.]

[What are the consequences if the problem is not addressed?]

Decision Drivers

edit
  • [driver 1, e.g., a force, facing concern ]
  • [driver 2, e.g., a force, facing concern, …]
  • …

Considered Options

edit
  • [option 1]
  • [option 2]
  • [option 3]
  • …

Decision Outcome

edit

Chosen option: "[option 1]", because [justification. e.g., only option, which meets must-have criterion decision driver | which resolves force | … | comes out best (see below)].

Positive Consequences

edit
  • [e.g., improvement of quality attribute satisfaction, follow-up decisions required, …]
  • …

Negative Consequences

edit
  • [e.g., compromising quality attribute, follow-up decisions required, …]
  • …

For Each Option Considered, Pros and Cons

edit

Address any significant differences in system behavior, non-functionals, team dependencies, and strategic decision drivers

[option 1]

edit

[example | description | pointer to more information | …]

  • Good, because [argument a]
  • Good, because [argument b]
  • Bad, because [argument c]
  • …

[option 2]

edit

[example | description | pointer to more information | …]

  • Good, because [argument a]
  • Good, because [argument b]
  • Bad, because [argument c]
  • …

[option 3]

edit

[example | description | pointer to more information | …]

  • Good, because [argument a]
  • Good, because [argument b]
  • Bad, because [argument c]
  • …
edit
  • [Link type] [Link to ADR]
  • …

Additional Comments

edit

[Anyone can add anything that doesn’t neatly fit into the format above]

Was this Helpful

edit

If you just read this TDR, please let us know how to improve this template.

edit
  • Did the TDR provide the information you were looking for?
  • How was it over done?
  • How was it under done?
Retrieved from "https://www.mediawiki.org/w/index.php?title=Data_Platform_Engineering/Technical_Decision_Record&oldid=6165824"