編譯 | 翟珂、云昭

如果你是軟件開發(fā)人員或架構(gòu)師，一定知道開發(fā)行業(yè)里普遍存在這樣一種“文檔糾結(jié)癥”：一面抱怨寫文檔浪費時間，一面抱怨別人不寫文檔?？梢哉f，設(shè)計文檔可以說是日常工作中非常重要但又容易被忽略的部分。

編寫軟件設(shè)計文檔（SDD）的好處很多，其主要目的是使開發(fā)者對軟件設(shè)計進行強制性思考, 并收集他人的反饋, 以便更好地完成工作。同時也是讓其他人了解系統(tǒng)的參考文檔。好的文檔與項目成功之間有很強的關(guān)聯(lián)性。

相信很多網(wǎng)上有很多相關(guān)的文章、教程來告訴你如何寫SDD，這里不再贅述。但很多人往往犯了“教條”主義：設(shè)計文檔雖然包含大量段落、圖表和細(xì)節(jié)，但卻并沒有產(chǎn)生多大價值，甚至連所需要解決的問題都沒有覆蓋到。

在本文中，我們將討論軟件設(shè)計文檔中最容易忽略的幾個問題，避免因這些疏忽而誤導(dǎo)了讀者，甚至延誤了所負(fù)責(zé)的項目。

什么時候才需要設(shè)計文檔

每當(dāng)有新的需求或者原有功能變更的時候，我們就需要先編寫設(shè)計文檔，然后在進行相關(guān)開發(fā)。該設(shè)計文檔需要由所有項目干系人進行審查。

設(shè)計文檔是 SDLC （軟件開發(fā)生命周期）設(shè)計階段的結(jié)果。設(shè)計文檔的輸入標(biāo)準(zhǔn)就是一份需求明確的需求文檔。一旦需求在收集階段最終確定，那么設(shè)計階段就要開始了。

寫給誰看很重要

這是設(shè)計文檔中最被低估的部分，沒有這部分會給讀者帶來很多困惑。每個設(shè)計文檔都應(yīng)該有一個編寫目的，其中提到該設(shè)計文檔的目標(biāo)讀者對象。

假設(shè)我們編寫了一個高級設(shè)計文檔 (HLDD) 來實現(xiàn)服務(wù)間通信。該文檔包含了我們需要在基礎(chǔ)架構(gòu)哪些方面進行更改，以及實現(xiàn)發(fā)布-訂閱模型需要哪些技術(shù)棧等。此 HLDD 面向于基礎(chǔ)架構(gòu)和微服務(wù)相關(guān)團隊的架構(gòu)師。

如果沒有編寫目的，導(dǎo)致初級開發(fā)人員閱讀了該文檔，他們很可能無法理解 SDD 的所有內(nèi)容，以至于問一堆不明確的問題，這樣就造成了作者回復(fù)的負(fù)擔(dān)。

為避免出現(xiàn)這種情況，建議你提及文檔的面向讀者群體。

識別未知因素

在理想情況下，一旦需求和變更點明確，就會開始編寫SDD。但是對于比較復(fù)雜的需求來說，總是會有一些未知因素。

如果我們在編寫SDD時能夠發(fā)現(xiàn)這些未知因素，并且了解具體內(nèi)容，那么將有助于作出決策（評估工時等）。當(dāng)我們知道了這些未知因素后就可以與相關(guān)人員探討解決方法，然后去修改我們的設(shè)計方案。

這十分必要。平時工作中不乏因為沒有預(yù)測不確定因素而造成難以挽回的損失。如果文檔寫作者只注意在線下“沖鋒”解決問題，而忽略了在文檔中考慮并記錄這些，隨著時間的推移，SDD的作者要么換了團隊，要么跳槽了，導(dǎo)致這些未知因素沒有人知道，導(dǎo)致沒有人能去追蹤。如果這種現(xiàn)象發(fā)生在復(fù)雜的 SDD 中，那么它會在 SDLC 的實現(xiàn)階段產(chǎn)生巨大的問題。

需求分析 

在收集需求階段，大部分的時間都在分析需求。到設(shè)計階段，我們只需要跟進相關(guān)負(fù)責(zé)人來探討這些問題。然而有時我們在編寫 SDD 時會發(fā)現(xiàn)新的需求，所以還需要添加、跟蹤并且梳理這些需求。最好使用表格的形式來列舉這些，如下面的表格：

風(fēng)險分析 

在寫SDD的時候，可能會有一些不確定的點。例如，我們需要在分布式環(huán)境中部署代碼，由于與AWS（亞馬遜云計算）商務(wù)團隊的洽談已進入到了最后階段，那么在我們的設(shè)計文檔中就需要體現(xiàn)，考慮到這個項目將被部署在AWS上。

由于交易尚未敲定，不可預(yù)見，所以有可能公司臨時決定不使用AWS而選擇GCP（谷歌云計算）來部署代碼。在這種情況下，我們的SDD中的內(nèi)容就需要修改。因此，與AWS的未完成交易對我們而言是一個風(fēng)險。

在設(shè)計文檔中提及風(fēng)險，并且闡述影響范圍，這樣就會讓所有項目干系人有意識的關(guān)注這些問題。

DOD（完成的定義）

每個設(shè)計文檔都有不同的編寫目的，因此無法以一個標(biāo)準(zhǔn)去衡量設(shè)計文檔的 DOD 應(yīng)該是什么。但是，一般來說，如果解決了以下幾點，則認(rèn)為設(shè)計文檔已完成：

• SDD是參考需求和分析文檔后創(chuàng)建的。
• 面向的所有讀者都能夠理解SDD。
• SDD 涵蓋了本文前面提到的所有要點。
• 通過設(shè)計文檔，可以快速的拆分任務(wù)。
• 設(shè)計文檔得到了所有項目干系人的批準(zhǔn)。

結(jié)論

除了上面所說的幾點，還有很多其他細(xì)節(jié)可以幫助我們寫好SDD，例如文檔的長度多少為宜、圖表的數(shù)量多少合適等，這里就不一一做介紹了。當(dāng)你掌握了這些要素后，相信一定可以寫出高價值含量的設(shè)計文檔。

原文鏈接：

https://dzone.com/articles/ingredients-for-a-perfect-design-document?fromrel=true

譯者介紹

翟珂，51CTO社區(qū)編輯，目前在杭州從事軟件研發(fā)工作，做過電商、征信等方面的系統(tǒng)，享受分享知識的過程，充實自己的生活。