How to read and document decisions

Certain decisions affect and influence the architecture, as such they are worth documenting explicitly. During implementation countless small decisions are done, however it’s not about documenting everyday programming choices (which are often done in Git commits for example).

Structure

Problem

Describe the problem that this decision should solve or requirements that need to be implemented. It should be understandable even if not having participated in discussions (link to requirements and other decisions in the next sections).

Relevant requirements

List and link any requirements that influence the problem or constraint the proposals.

Relevant decisions

List and link any dependent decisions related to these decisions. This is most used in cases where previous decisions lead to new problems or follow-up decisions.

Proposals

Multiple proposals outline which alternatives were considered for deciding. Describe them detailed enough for traceability and comprehensibility. Consider something like the following AsciiDoc source:

== Proposals

[qanda] (1)
Proposal 1:: (2)
Description of proposal 1

Proposal 2::
Description of proposal 2

1	`qanda` (read: Q&A for a FAQ page) formats the proposals with numbering and highlighting.
2	The title of the proposal, to be referenced from the `Decisions` section.

Decision

What’s the accepted proposal? One line identifying the proposal should be enough.

Rationale

What are the main reasons why a proposal was chosen? The reasons shouldn’t extend the description of a proposal, only further explain why this proposal was in favor of others.

Certain types of decisions don’t impact the architecture. In those cases, consider just documenting a definition even if the definition took multiple discussions.