編寫架構文件的最佳實踐 - Singh

一個有據可查的架構可能是成功與失敗專案之間的區別。它帶來了巨大的收益，並確保系統易於理解、設計得周到，並且可以與他人交流。在您記錄的內容中務實，使其成為流程的一部分，並在您的架構、設計和解決方案中不斷深思熟慮，以滿足您的業務需求。

• 記錄重要的事情和重要的時間。並不是所有的事情都需要在一開始就記錄下來。架構和相應的設計可能是流動的，尤其是在測試新功能、處於試點模式或構建新系統時。有些可能是暫時的，而有些則需要是永久性的，所以從工作程式碼開始，所需的最小集，並隨著時間的推移而擴充套件。
• 從一開始就捕獲所有架構決策。有機架構不是架構。架構是深思熟慮的、突發的和有意的，避免了我們質疑為什麼系統及其元件以某種方式設計的情況，並保持對導致特定方法的力量的明確性。記錄決策將使您能夠回顧並驗證解決方案是否繼續滿足業務需求，並在擴充套件或重構它們時提供幫助。
• 跟蹤架構債務以保持對需要解決的問題的當前管理良好的記錄，並促進產品級別的規劃和待辦事項梳理。必須不惜一切代價避免無證債務。
• 將文件架構作為流程的一部分，而不是作為追趕活動或在有時間時，因為永遠沒有時間。將“設計完成”定義為完成架構、其設計和所需的工件。正如未經測試的程式碼會引入業務風險一樣，未記錄的架構也會帶來業務風險。
• 最大化工件的自動化。雖然有些工件需要手動工作，但完全有可能自動建立其他工件，包括上下文和介面圖、流程流、服務和 API 目錄以及基礎架構圖。利用自記錄技術和自動化，可以根據構建的內容和正在執行的內容保持工件的最新狀態。