編譯 | 翟珂、云昭
如果你是軟件開發人員或架構師，一定知道開發行業里普遍存在這樣一種“文檔糾結癥”：一面抱怨寫文檔浪費時間，一面抱怨別人不寫文檔。可以說，設計文檔可以說是日常工作中非常重要但又容易被忽略的部分。
編寫軟件設計文檔（SDD）的好處很多，其主要目的是使開發者對軟件設計進行強制性思考, 并收集他人的反饋, 以便更好地完成工作。同時也是讓其他人了解系統的參考文檔。好的文檔與項目成功之間有很強的關聯性。
相信很多網上有很多相關的文章、教程來告訴你如何寫SDD，這里不再贅述。但很多人往往犯了“教條”主義：設計文檔雖然包含大量段落、圖表和細節，但卻并沒有產生多大價值，甚至連所需要解決的問題都沒有覆蓋到。
在本文中，我們將討論軟件設計文檔中最容易忽略的幾個問題，避免因這些疏忽而誤導了讀者，甚至延誤了所負責的項目。
什么時候才需要設計文檔
每當有新的需求或者原有功能變更的時候，我們就需要先編寫設計文檔，然后在進行相關開發。該設計文檔需要由所有項目干系人進行審查。
設計文檔是 SDLC （軟件開發生命周期）設計階段的結果。設計文檔的輸入標準就是一份需求明確的需求文檔。一旦需求在收集階段最終確定，那么設計階段就要開始了。
寫給誰看很重要
這是設計文檔中最被低估的部分，沒有這部分會給讀者帶來很多困惑。每個設計文檔都應該有一個編寫目的，其中提到該設計文檔的目標讀者對象。
假設我們編寫了一個高級設計文檔 (HLDD) 來實現服務間通信。該文檔包含了我們需要在基礎架構哪些方面進行更改，以及實現發布-訂閱模型需要哪些技術棧等。此 HLDD 面向于基礎架構和微服務相關團隊的架構師。
如果沒有編寫目的，導致初級開發人員閱讀了該文檔，他們很可能無法理解 SDD 的所有內容，以至于問一堆不明確的問題，這樣就造成了作者回復的負擔。
為避免出現這種情況，建議你提及文檔的面向讀者群體。
識別未知因素
在理想情況下，一旦需求和變更點明確，就會開始編寫SDD。但是對于比較復雜的需求來說，總是會有一些未知因素。
如果我們在編寫SDD時能夠發現這些未知因素，并且了解具體內容，那么將有助于作出決策（評估工時等）。當我們知道了這些未知因素后就可以與相關人員探討解決方法，然后去修改我們的設計方案。
這十分必要。平時工作中不乏因為沒有預測不確定因素而造成難以挽回的損失。如果文檔寫作者只注意在線下“沖鋒”解決問題，而忽略了在文檔中考慮并記錄這些，隨著時間的推移，SDD的作者要么換了團隊，要么跳槽了，導致這些未知因素沒有人知道，導致沒有人能去追蹤。如果這種現象發生在復雜的 SDD 中，那么它會在 SDLC 的實現階段產生巨大的問題。
需求分析
在收集需求階段，大部分的時間都在分析需求。到設計階段，我們只需要跟進相關負責人來探討這些問題。然而有時我們在編寫 SDD 時會發現新的需求，所以還需要添加、跟蹤并且梳理這些需求。最好使用表格的形式來列舉這些，如下面的表格：
風險分析
在寫SDD的時候，可能會有一些不確定的點。例如，我們需要在分布式環境中部署代碼，由于與AWS（亞馬遜云計算）商務團隊的洽談已進入到了最后階段，那么在我們的設計文檔中就需要體現，考慮到這個項目將被部署在AWS上。
由于交易尚未敲定，不可預見，所以有可能公司臨時決定不使用AWS而選擇GCP（谷歌云計算）來部署代碼。在這種情況下，我們的SDD中的內容就需要修改。因此，與AWS的未完成交易對我們而言是一個風險。
在設計文檔中提及風險，并且闡述影響范圍，這樣就會讓所有項目干系人有意識的關注這些問題。
DOD（完成的定義）
每個設計文檔都有不同的編寫目的，因此無法以一個標準去衡量設計文檔的 DOD 應該是什么。但是，一般來說，如果解決了以下幾點，則認為設計文檔已完成：
- SDD是參考需求和分析文檔后創建的。
- 面向的所有讀者都能夠理解SDD。
- SDD 涵蓋了本文前面提到的所有要點。
- 通過設計文檔，可以快速的拆分任務。
- 設計文檔得到了所有項目干系人的批準。
結論
除了上面所說的幾點，還有很多其他細節可以幫助我們寫好SDD，例如文檔的長度多少為宜、圖表的數量多少合適等，這里就不一一做介紹了。當你掌握了這些要素后，相信一定可以寫出高價值含量的設計文檔。
原文鏈接：
https://dzone.com/articles/ingredients-for-a-perfect-design-document?fromrel=true
譯者介紹
翟珂，51CTO社區編輯，目前在杭州從事軟件研發工作，做過電商、征信等方面的系統，享受分享知識的過程，充實自己的生活。
