Major decisions on architecture and design have so far primarily been recorded in code comments or not recorded at all. While the former has been an acceptable approach, the latter has not as important information has resided only with the person who made the decision.
We want to avoid siloing of information on the reasons for why important decisions were made and we want to do so in a way that is both transparent and easy to maintain. Documenting architecture decisions should be no different than documenting code in that the documentation is written as plain text and lives with the rest of the code base.
Moving forward, we will make use of so-called architecture decision reports (ADR) as described in Documenting architecture decisions by Michael Nygard. The ADRs will live in the docs/architecture/decisions directory and will follow the format outlined in docs/architecture.md.
Accepted.
By writing and maintaining ADRs, all developers, future and present, will be able to make sense of past decisions and decide whether they still apply or not. This of course assumes that the ADRs have actually been written, which we as developers and maintainers must be vigilant to ensure. The extra work in the short term will however pay off in the long term.