1. Use ADR with a Custom Template

Context and Motivation

We’re starting a new software project from scratch. In the process we will discuss solutions and make decisions. We want to document every meaningful decision. For this task there is a practice, called architectural decision records, ADR.

Our motivation is to make better software through better decisions, learn to research and make informed architectural decisions, and learn the ADR practice itself.

For each decision it is important to consider and remember:

  • what we’ve decided to do,
  • why we made this decision,
  • what is the impact of this decision,
  • what we learnt in the process.

We’re already using rST, Sphinxdoc and readthedocs.com for documentation. It would be good to make AD records a part of this documentation.

Options

We have considered the following opitons:

  • refrain from using ADR, just discuss things and reflect decisions in tasks and code;
  • use default template and CLI-tool by Michael Nygard;
  • use one of the other templates;
  • write and use a custom template.

Decision

We have decided to use the architectural decision records.

We have developed a custom template, based on Michael Nygard’s. The template is formatted in rST and can be found in Record Template.

Records are a part of Bot’s documentation. They’re placed in ./sites/docs/adr/ and placed under ./sites/docs/adr.rst. File name consists of the ADR number and shortened title, cabob-case:

0001-use-adr.rst

Status

Proposed

Consequences

From using ADR overall:

  • Technical decisions in the project will become explicit, which is better than implicit.
  • New contributors will understand the reasoning behind decisions.
  • Developers will explicitly focus on researching and making reasonable decisions.
  • Writing down decisions will take extra time, but is worth it.

On using a custom template:

  • Reflects exactly what we need.
  • Using rST allows making ADR a part of documentation.
  • We won’t be able to use ADR tools, made for other templates. Although, we may be able to adapt them.