Skip to content

Instantly share code, notes, and snippets.

@DmytroLitvinov
Created March 11, 2024 08:47
Show Gist options
  • Save DmytroLitvinov/8cae5975248ad43e12012e05cad78432 to your computer and use it in GitHub Desktop.
Save DmytroLitvinov/8cae5975248ad43e12012e05cad78432 to your computer and use it in GitHub Desktop.
Decision record template

Decision record template (based on Michael Nygard template)

This is the template in Documenting architecture decisions - Michael Nygard.

In each ADR file, write these sections:

Title

The title is not supposed to be about the decision; it is the decision. You see this vagueness in ADR titles like "Database decision". The title is not supposed to be about the decision; it is the decision.

I.e., "SQL Server adoption" is a decision, "MongoDB adoption" is a different decision, etc.

Should be short description of the architectural solution, should be informative and clear to quickly navigate what the entry is about.

That means, each alternative is a separate decision, so "SQL Server adoption" is one decision and "MongoDB adoption" is a different decision written up in a different ADR. You decide to accept one of these and reject the other, but both are recorded. (c) https://mastodon.social/@kevlin/109517779458716485

Status

What is the status, such as proposed, accepted, rejected, deprecated, superseded, requests for comments etc.?

Context

What is the issue that we're seeing that is motivating this decision or change?

Decision

What is the change that we're proposing and/or doing? This section describes our response to these forces. It is stated in full sentences, with active voice. "We will …"

The very essence of the architectural solution and its full justification. It is important to pay special attention to the justification of the solution, to answer the question "why".

Consequences

What becomes easier or more difficult to do because of this change? This section describes the resulting context, after applying the decision. All consequences should be listed here, not just the "positive" ones. A particular decision may have positive, negative, and neutral consequences, but all of them affect the team and project in the future.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment