編譯 | 翟珂、云昭

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

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

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

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

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

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

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

寫給誰看很重要

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

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

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

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

識(shí)別未知因素

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

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

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

需求分析 

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

風(fēng)險(xiǎn)分析 

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

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

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

DOD（完成的定義）

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

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

結(jié)論

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

原文鏈接：

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

譯者介紹

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