作者：蒂莫西·海伊（TimothyHigh）
在軟件開發社區，對於文檔尤其是關於軟件自身設計的文檔的價值，爭論頗多。分歧一般集中於兩處，一處是“詳細的前期設計（big upform design）”的有效價值，另一處則是使設計文檔和不斷變化的代碼庫保持同步的難易程度。
記錄軟件架構決策理由的文檔，長期有用，又無須爲之付出過多維護精力，具有很高的投資回報價值。正如馬克·理查茲（MarkRichards）在《取捨的藝術》一篇（譯註1）中所說的，定義軟件架構，就是要在質量屬性、成本、時間以及其他各種因素之間，做出正確的權衡。此份文檔應能向你自己、經理人員、開發人員及軟件的其他利益相關者，清楚闡明選擇某種解決方案，而非另外一種的原因，包括其中做出的權衡。有沒有打着減少硬件和許可費用的幌子，犧牲了系統的水平伸縮性（horizontal scalability）？雖然縮短了數據交換的整體響應時間，但數據加密是否足夠安全？
根據項目的不同，可以靈活選擇合適的文檔格式記錄架構決策的方方面面，格式可以是文本、維基（wiki）或博客（blog）形式的速記備忘錄，也可以使用更爲正式的模板。無論使用何種形式和格式，些文檔都應回答以下基本問題：“我們做了什麼決策？”“爲什麼這樣決策？”有一個稍次要的問題，經常有人會問到，因而也要記錄下來：“我們還考慮過哪些解決方案？爲什麼沒有采用？”（事實上，有人經常會這樣問：“爲什麼我這個方案不行？”）。此文檔應該放在容易查找，可被搜索的地方，以備不時之需。
這類文檔遲早會派上用場，比方說：
- 可以作爲和開發人員進行溝通的工具，說明應遵循的重要架構原則。
- 當開發人員對架構背後的邏輯提出質疑時，使團隊成員能夠“就事論事”，甚至能夠避免一場“兵變（mutiny）（譯註2）”（如果事實表明你的決策站不住腳，便應虛心接受批評）。
- 向經理和利益相關者說明這樣構建軟件的確切原因（比如，採用某種較爲昂貴的硬件或軟件的必要性等）。
- 要把項目移效給下任架構師時（你有多少次在接手軟件時很疑惑原來的設計者究竟爲什麼要採用那種做法？）。
然而，從這種實踐中可獲得的最重要好處是：
- 它逼着你明確說出理由，有助於確保基礎（foundation）是紮實穩固的（參見下一條文《挑戰假設尤其是你自己的》）。
- 如果相關條件發生變化，需要對決策重新評估，它可以作爲一個起點。
譯註1：參見本書第22篇《取捨的藝術》。
譯註2：指架構師和團隊成員間不是進行“就事論事”的溝通，而是進行帶有人身攻擊性質的爭論，最終破壞團隊的健康。