撰写优质 ADR 的建议

优质 ADR 的特征:

• 理由(Rationale):解释做出该项 AD 的原因。可以包括背景(见下文)、各种潜在选择的利弊、功能对比、成本效益讨论等。

• 具体(Specific):每个 ADR 应只针对一项 AD,而不是多项 AD。

• 时间戳(Timestamps):标明 ADR 中每一项内容的撰写时间。这对于可能随时间变化的方面尤为重要,例如成本、进度、扩展规模等。

• 不可变(Immutable):不要修改 ADR 中已有的信息。相反,应通过添加新信息来修订该 ADR,或通过创建新的 ADR 来取代它。

ADR 中优质“背景”(Context)部分的特征:

• 说明你所在组织的处境和业务优先事项。

• 包含基于团队的社会构成和技能构成所做的理由与考量。

• 包含相关的利弊,并用符合你的需求和目标的方式加以描述。

ADR 中优质“后果”(Consequences)部分的特征:

• 解释做出该决策之后会产生什么。这可以包括影响、结果、产出、后续跟进等。

• 包含任何后续 ADR 的信息。一个 ADR 引发对更多 ADR 的需求相当常见,例如某个 ADR 做出了一项重大的总体选择,进而产生了更多较小决策的需求。

• 包含任何事后复盘流程。团队通常会在每个 ADR 做出一个月后对其进行评审,将 ADR 中的信息与实际发生的情况加以比较,以便学习和成长。

新的 ADR 可以取代以前的 ADR:

• 当做出的某项 AD 替代或否定了以前的某个 ADR 时,应创建一个新的 ADR