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

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

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

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

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

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

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

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

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

        設(shè)計文檔描述了問題的解決方案。因為每個問題的性質(zhì)不一樣，所以設(shè)計文檔的結(jié)構(gòu)也不一樣。

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

        標題和人物

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

        摘要

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

        背景

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

        目標和非目標

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

• 描述項目對用戶的影響——你的用戶可能是另一個工程團隊或另一個系統(tǒng)。

• 指定如何使用指標來度量項目的成功——如果可以鏈接到指標儀表盤那就更好了。

        非目標也同樣重要，用于描述項目不會解決哪些問題，讓每個人都達成共識。

        里程碑

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

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

        開始日期：2018 年 6 月 7 日

        里程碑 1——以暗模式運行新系統(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)前的實現(xiàn)之外，還應(yīng)該通過示例來說明用戶如何與系統(tǒng)發(fā)生交互以及數(shù)據(jù)是如何流經(jīng)系統(tǒng)的。

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

        提議的方案

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

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

        其他替代方案

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

        監(jiān)控和警報

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

        跨團隊影響

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

• 它的成本是多少？

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

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

• 它會帶來哪些負面后果和副作用？

• 支持團隊該如何與客戶溝通？

        討論

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

        詳細的范圍和時間表

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

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

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

        怎樣才能寫好文檔

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

        盡可能保持簡單

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

• 用詞簡單

• 使用短句

• 使用符號列表和編號列表

• 提供具體的示例

        添加圖表

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

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

        包含數(shù)字

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

        加入趣味性

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

        自審

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

        假期測試

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

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

        流程

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

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

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

        在你了解了如何進行項目之后，請執(zhí)行以下步驟：

• 請你團隊中經(jīng)驗豐富的工程師或技術(shù)負責(zé)人來評審你的文檔。理想情況下，評審人員應(yīng)該是一個受到尊重并且對問題邊緣情況已經(jīng)很熟悉的人。

• 在有白板的會議室里進行評審。

• 向評審人員描述你正在解決的問題（這是非常重要的一步，不要跳過它?。?。

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

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

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

        在添加評審人員名字時，可以考慮為特定的問題添加不同的評審人員（例如 SRE 和安全工程師）。

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

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

        如果一個主題超過了 5 條評論，那么進行面對面討論往往會更有效率。請記住，即使無法讓每個人都達成共識，你仍然可以拍板。

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

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

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

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

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

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

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

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

5. 你決定停止這個項目去做其他工作。

        在本文開頭，我們說設(shè)計文檔的目的是確保正確地完成工作。在上述的示例中，因為有了軟件設(shè)計文檔，你只花了 8 天時間而不是浪費了幾個月才決定要中止項目。在我看來，這似乎也是一個非常成功的結(jié)果。