One of the proponents of Architecture Decision Records, Joel Parker Henderson, has collected suggestions for good architecture decision records.

We recommend to follow his suggestions:

We quote only the first part of his collection:

Characteristics of a good ADR:

  • Rational: Explain the reasons for doing the particular AD. This can include the context, pros and cons of various potential choices, feature comparions, cost/benefit discussions, and more.
  • Specific: Each ADR should be about one AD, not multiple ADs.
  • Timestamps: Identify when each item in the ADR is written. This is especially important for aspects that may change over time, such as costs, schedules, scaling, and the like.
  • Immutable: Don’t alter existing information in an ADR. Instead, amend the ADR by adding new information, or supersede the ADR by creating a new ADR.