作為一名軟件工程師，我花了很多時(shí)間在閱讀和撰寫設(shè)計(jì)文檔上。在磨礪了數(shù)百篇文檔之后，我發(fā)現(xiàn)，優(yōu)秀的設(shè)計(jì)文檔與項(xiàng)目的成功之間有著密切的聯(lián)系。

        這篇文章將介紹怎樣才能寫出一份優(yōu)秀的設(shè)計(jì)文檔。

        為什么要寫設(shè)計(jì)文檔？

        設(shè)計(jì)文檔也就是技術(shù)規(guī)范，用于描述你打算如何解決問(wèn)題。已經(jīng)有很多文章說(shuō)明了為什么在開始編碼之前要先寫設(shè)計(jì)文檔，這里不再贅述，不過(guò)我想再補(bǔ)充一句：

        設(shè)計(jì)文檔是確保正確完成工作最有用的工具。

        設(shè)計(jì)文檔的主要目的是迫使你對(duì)軟件設(shè)計(jì)展開縝密的思考，并收集他人的反饋，以便更好地完成你的工作。人們通常認(rèn)為，設(shè)計(jì)文檔的目的是讓其他人了解某個(gè)系統(tǒng)，或者作為參考文檔。這些只是設(shè)計(jì)文檔帶來(lái)的有益的副作用，但絕不是它們的根本目的。

        從經(jīng)驗(yàn)來(lái)看，如果你的項(xiàng)目需要一個(gè)人月或更長(zhǎng)時(shí)間，那么就應(yīng)該編寫設(shè)計(jì)文檔。另外，一些小型項(xiàng)目也可以從迷你設(shè)計(jì)文檔中獲益。

        但不同的工程團(tuán)隊(duì)，甚至是同一團(tuán)隊(duì)中的工程師，他們編寫設(shè)計(jì)文檔的方式存在很大差異。接下來(lái)，讓我們來(lái)談?wù)剝?yōu)秀設(shè)計(jì)文檔的內(nèi)容、風(fēng)格和流程應(yīng)該是怎樣的。

        設(shè)計(jì)文檔應(yīng)該包含哪些內(nèi)容？

        設(shè)計(jì)文檔描述了問(wèn)題的解決方案。因?yàn)槊總€(gè)問(wèn)題的性質(zhì)不一樣，所以設(shè)計(jì)文檔的結(jié)構(gòu)也不一樣。

        下面列出了一個(gè)清單，你至少可以考慮在文檔中包含這些內(nèi)容。

        標(biāo)題和人物

        設(shè)計(jì)文檔的標(biāo)題、作者（應(yīng)該與計(jì)劃參與項(xiàng)目的人員名單相同）、文檔的評(píng)審人員（我們將在“流程”部分詳細(xì)討論），以及文檔的最后更新日期。

        摘要

        摘要可以幫助公司的每位工程師理解文檔的內(nèi)容，并決定是否需要繼續(xù)閱讀文檔的剩余部分。摘要最多可以包含 3 段內(nèi)容。

        背景

        描述要解決什么問(wèn)題、為什么需要這個(gè)項(xiàng)目、人們需要哪些知識(shí)才可以評(píng)估這個(gè)項(xiàng)目，以及它與技術(shù)戰(zhàn)略、產(chǎn)品戰(zhàn)略或團(tuán)隊(duì)的季度目標(biāo)之間的關(guān)系。

        目標(biāo)和非目標(biāo)

        目標(biāo)部分應(yīng)該包括：

• 描述項(xiàng)目對(duì)用戶的影響——你的用戶可能是另一個(gè)工程團(tuán)隊(duì)或另一個(gè)系統(tǒng)。

• 指定如何使用指標(biāo)來(lái)度量項(xiàng)目的成功——如果可以鏈接到指標(biāo)儀表盤那就更好了。

        非目標(biāo)也同樣重要，用于描述項(xiàng)目不會(huì)解決哪些問(wèn)題，讓每個(gè)人都達(dá)成共識(shí)。

        里程碑

        一系列可衡量的檢查點(diǎn)，你的 PM 和上司可以借助它們大致了解項(xiàng)目的每個(gè)部分將在什么時(shí)間完成。如果項(xiàng)目時(shí)間超過(guò) 1 個(gè)月，我建議你將項(xiàng)目分解為面向用戶的里程碑。

        在設(shè)定里程碑時(shí)可以使用日歷日期，把延期、假期、會(huì)議等因素都考慮進(jìn)去。例如：

        開始日期：2018 年 6 月 7 日

        里程碑 1——以暗模式運(yùn)行新系統(tǒng) MVP：2018 年 6 月 28 日

        里程碑 2——棄用舊系統(tǒng)：2018 年 7 月 4 日

        結(jié)束日期：在新系統(tǒng)中添加新特性 X、Y、Z：2018 年 7 月 14 日

        如果其中一些里程碑的 ETA 發(fā)生變化，需要在此處添加 [更新]，相關(guān)人員可以很容易看到更新的內(nèi)容。

        當(dāng)前的方案

        除了描述當(dāng)前的實(shí)現(xiàn)之外，還應(yīng)該通過(guò)示例來(lái)說(shuō)明用戶如何與系統(tǒng)發(fā)生交互以及數(shù)據(jù)是如何流經(jīng)系統(tǒng)的。

        這個(gè)時(shí)候可以使用用戶故事。請(qǐng)記住，你的系統(tǒng)可能擁有不同類型的用戶，他們的使用場(chǎng)景也不盡相同。

        提議的方案

        有人把這部分稱為技術(shù)架構(gòu)。這部分也可以通過(guò)用戶故事來(lái)進(jìn)行具體化，可以包含多個(gè)子部分和圖表。

        先從大處著手，然后填充細(xì)節(jié)。你要做到即使你在某個(gè)荒島上度假，團(tuán)隊(duì)的其他工程師也能按照你的描述來(lái)實(shí)現(xiàn)解決方案。

        其他替代方案

        在提出上述解決方案的同時(shí)，你還考慮了其他的方案了嗎？替代方案的優(yōu)點(diǎn)和缺點(diǎn)是什么？你是否考慮使用第三方解決方案——或使用開源解決方案——來(lái)解決問(wèn)題，而不是自己構(gòu)建解決方案？

        監(jiān)控和警報(bào)

        人們經(jīng)常把這部分視為馬后炮，甚至直接忽略掉。而在發(fā)生問(wèn)題后，他們就手忙腳亂，卻不知道該怎么辦，也不知道為什么會(huì)發(fā)生這些問(wèn)題。

        跨團(tuán)隊(duì)影響

• 這樣會(huì)增加輪班待命和 DevOps 的負(fù)擔(dān)嗎？

• 它的成本是多少？

• 它會(huì)增加系統(tǒng)延遲嗎？

• 它會(huì)暴露系統(tǒng)安全漏洞嗎？

• 它會(huì)帶來(lái)哪些負(fù)面后果和副作用？

• 支持團(tuán)隊(duì)該如何與客戶溝通？

        討論

        這部分可以包含任何你不確定的問(wèn)題、你想讓閱讀文檔的人一起權(quán)衡的有爭(zhēng)議的決定、對(duì)未來(lái)工作的建議，等等。

        詳細(xì)的范圍和時(shí)間表

        這一部分的主要閱讀對(duì)象是參與該項(xiàng)目的工程師、技術(shù)主管和經(jīng)理。因此，這部分放在文檔的最后。

        從本質(zhì)上講，這是項(xiàng)目計(jì)劃的實(shí)施方式和時(shí)間細(xì)分，可以包含很多內(nèi)容。

        我傾向于將這一部分視為項(xiàng)目任務(wù)跟蹤器，因此每當(dāng)范圍估計(jì)發(fā)生變化時(shí)，我都會(huì)更新它。但這更像是個(gè)人偏好。

        怎樣才能寫好文檔

        在講完優(yōu)秀的設(shè)計(jì)文檔應(yīng)該包含哪些內(nèi)容之后，現(xiàn)在讓我們來(lái)談?wù)剬懽黠L(fēng)格。

        盡可能保持簡(jiǎn)單

        不要把設(shè)計(jì)文檔寫成你曾經(jīng)讀過(guò)的學(xué)術(shù)論文。論文是為了給期刊評(píng)論家留下深刻印象，而編寫設(shè)計(jì)文檔是為了描述你的解決方案，并從其他人那里獲得反饋。你可以通過(guò)以下方式讓文檔變得更清晰：

• 用詞簡(jiǎn)單

• 使用短句

• 使用符號(hào)列表和編號(hào)列表

• 提供具體的示例

        添加圖表

        圖表便于對(duì)幾種選項(xiàng)進(jìn)行比較，而且通常比文本更容易理解。我經(jīng)常用 Google Drawing 來(lái)創(chuàng)建圖表。

        請(qǐng)記得在截圖下方添加一個(gè)指向圖表源文件的鏈接，以便在發(fā)生變更時(shí)可以更新圖表。

        包含數(shù)字

        問(wèn)題的規(guī)模通常決定了解決方案的規(guī)模。為了更好地幫助評(píng)審人員了解情況，請(qǐng)?jiān)谖臋n中使用實(shí)際的數(shù)字，例如數(shù)據(jù)庫(kù)行數(shù)、用戶錯(cuò)誤數(shù)、延遲，以及這些數(shù)據(jù)與使用量之間的關(guān)系。（還記得大 O 表示法嗎？）

        加入趣味性

        記住，技術(shù)規(guī)范不是學(xué)術(shù)論文。另外，人們喜歡閱讀有趣的東西，但也不要為了趣味性而偏離了核心思想。

        自審

        在將設(shè)計(jì)文檔發(fā)給其他人評(píng)審之前，自己先假裝是評(píng)審人員。你對(duì)這份設(shè)計(jì)文檔有什么疑問(wèn)？然后在發(fā)出文檔之前把這些問(wèn)題解決掉。

        假期測(cè)試

        如果你在獨(dú)家，無(wú)法訪問(wèn)網(wǎng)絡(luò)，那么團(tuán)隊(duì)中的其他人是否可以讀懂這份文檔，并按照你的意圖實(shí)現(xiàn)文檔中的內(nèi)容？

        設(shè)計(jì)文檔的主要目的不是為了知識(shí)共享，但這是一種評(píng)估清晰度的好辦法，讓其他人可以為你提供有用的反饋。

        流程

        設(shè)計(jì)文檔可以幫你在浪費(fèi)大量時(shí)間實(shí)現(xiàn)錯(cuò)誤的解決方案或解決錯(cuò)誤的問(wèn)題之前獲得反饋。獲得良好反饋是一門藝術(shù)，但那是后話了?，F(xiàn)在，讓我們來(lái)討論下如何為設(shè)計(jì)文檔獲取反饋。

        首先，參與項(xiàng)目的每個(gè)人都應(yīng)該參與軟件設(shè)計(jì)過(guò)程。即使有很多決定是由技術(shù)主管做出的，那也沒(méi)關(guān)系，至少每個(gè)人都應(yīng)該參與討論，并接收他們的設(shè)計(jì)。

        其次，設(shè)計(jì)的過(guò)程并不一定是盯著白板，在上面畫出各種想法。你可以動(dòng)起手來(lái)，建立各種可能的解決方案原型。這與在寫好設(shè)計(jì)文檔之前就開始寫代碼是不一樣的。你完全可以隨意寫一些一次性的代碼來(lái)驗(yàn)證你的想法。為了確保你的代碼只是用于概念驗(yàn)證，原型代碼都不能合并到 master 上。

        在你了解了如何進(jìn)行項(xiàng)目之后，請(qǐng)執(zhí)行以下步驟：

• 請(qǐng)你團(tuán)隊(duì)中經(jīng)驗(yàn)豐富的工程師或技術(shù)負(fù)責(zé)人來(lái)評(píng)審你的文檔。理想情況下，評(píng)審人員應(yīng)該是一個(gè)受到尊重并且對(duì)問(wèn)題邊緣情況已經(jīng)很熟悉的人。

• 在有白板的會(huì)議室里進(jìn)行評(píng)審。

• 向評(píng)審人員描述你正在解決的問(wèn)題（這是非常重要的一步，不要跳過(guò)它?。?。

• 然后向評(píng)審人員解釋你想要怎樣實(shí)現(xiàn)你的想法，并說(shuō)服他們這是正確的解決方案。

        在開始正式編寫設(shè)計(jì)文檔之前完成所有這些步驟，可以讓你在投入更多時(shí)間并敲定解決方案之前盡快獲得反饋。通常情況下，即使實(shí)現(xiàn)方式可以保持不變，評(píng)審人員仍然會(huì)指出一些需要你覆蓋到的極端情況，或者指潛在的不明確的地方，并預(yù)測(cè)你以后可能會(huì)遇到的困難。

        然后，在你為設(shè)計(jì)文檔寫了粗稿之后，讓之前的評(píng)審人員再次閱讀它，并在設(shè)計(jì)文檔的“標(biāo)題和人物”部分寫下他們的名字，作為對(duì)評(píng)審人員的鼓勵(lì)，也表示他們是有責(zé)任對(duì)自己的評(píng)審行為負(fù)責(zé)的。

        在添加評(píng)審人員名字時(shí)，可以考慮為特定的問(wèn)題添加不同的評(píng)審人員（例如 SRE 和安全工程師）。

        在完成評(píng)審之后，請(qǐng)將設(shè)計(jì)文檔發(fā)給你的團(tuán)隊(duì)，以便獲得額外的反饋。我建議把這個(gè)時(shí)間限制在 1 周左右，以避免延期。盡量在一周內(nèi)解決他們留下的問(wèn)題。

        最后，如果你和評(píng)審人員及其他閱讀該文檔的工程師之間存在爭(zhēng)議，我強(qiáng)烈建議你將這些爭(zhēng)議放在文檔的“討論”部分。然后，與各方召開會(huì)議討論這些分歧。

        如果一個(gè)主題超過(guò)了 5 條評(píng)論，那么進(jìn)行面對(duì)面討論往往會(huì)更有效率。請(qǐng)記住，即使無(wú)法讓每個(gè)人都達(dá)成共識(shí)，你仍然可以拍板。

        在最近與同事談?wù)摯耸聲r(shí)，我了解到團(tuán)隊(duì)組有一個(gè)類似的過(guò)程，只是除了讓團(tuán)隊(duì)中經(jīng)驗(yàn)豐富的工程師或技術(shù)負(fù)責(zé)人來(lái)充當(dāng)評(píng)審人員之外，他們還建議讓不同團(tuán)隊(duì)的工程師評(píng)審設(shè)計(jì)文檔。我沒(méi)有嘗試過(guò)這個(gè)，但可以肯定的是，這樣有助于從擁有不同視角的人那里獲得反饋，從而進(jìn)一步提高文檔的質(zhì)量。

        在完成上述所有步驟之后，接下來(lái)就可以開始實(shí)現(xiàn)了！在實(shí)現(xiàn)設(shè)計(jì)的過(guò)程中，可以將設(shè)計(jì)文檔視為活動(dòng)的文檔。在對(duì)實(shí)現(xiàn)方案做出調(diào)整時(shí)，也一并更新文檔，這樣你就不需要向所有利益相關(guān)者反復(fù)解釋這些變化。

        那么，我們?nèi)绾卧u(píng)估一份設(shè)計(jì)文檔成功與否？

        我的同事對(duì)這個(gè)問(wèn)題的回答是：如果能夠獲得正確的投資回報(bào)率（ROI），那么設(shè)計(jì)文檔就是成功的。也就是說(shuō)，一份成功的設(shè)計(jì)文檔可能會(huì)導(dǎo)致：

1. 你花了 5 天時(shí)間編寫設(shè)計(jì)文檔，迫使你對(duì)技術(shù)架構(gòu)的不同部分進(jìn)行了充分的思考。

2. 你從評(píng)審人員那里獲得反饋，知道架構(gòu)中某些部分具有較高的風(fēng)險(xiǎn)。

3. 你決定先解決這些問(wèn)題，以便降低項(xiàng)目的風(fēng)險(xiǎn)。

4. 3 天后，你發(fā)現(xiàn)這些問(wèn)題要么不可能發(fā)生，要么比你原先想象的要困難得多。

5. 你決定停止這個(gè)項(xiàng)目去做其他工作。

        在本文開頭，我們說(shuō)設(shè)計(jì)文檔的目的是確保正確地完成工作。在上述的示例中，因?yàn)橛辛塑浖O(shè)計(jì)文檔，你只花了 8 天時(shí)間而不是浪費(fèi)了幾個(gè)月才決定要中止項(xiàng)目。在我看來(lái)，這似乎也是一個(gè)非常成功的結(jié)果。