撰寫優質 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