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

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

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

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

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]

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

List of keywords to assist in finding relevant TDRs

Context and Problem Statement

[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

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

Considered Options

[option 1]
[option 2]
[option 3]
…

Decision Outcome

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

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

Negative Consequences

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

For Each Option Considered, Pros and Cons

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

[option 1]

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

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

[option 2]

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

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

[option 3]

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

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

Links

[Link type] [Link to ADR]
…

Additional Comments

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

Was this Helpful

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

Did the TDR provide the information you were looking for?
How was it over done?
How was it under done?