Recording architectural decisions
Moving to the implementation side, we now face decision-making issues on how this application will be developed. The decisions that we make will have lasting repercussions for a project, and over the life of the project, the motivations for why a decision was made can be lost.
Enter the architecture decision record. The most popular format for these records comes from Michael Nygard (https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions.html) who suggested the following format, shown here in Markdown:
# {RecordNum}. {Title}
## 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?
## Status
Proposed, Accepted, Rejected, Superseded, Deprecated
## Consequences
What becomes easier or more difficult to do because of this change
An architectural decision record should be made each time a significant change is being made...