作為一名軟體工程師，我花了很多時間閱讀和編寫設計文件。在閱讀了數百份設計文件後，我親眼目睹了優秀的設計文件與專案最終成功之間的密切關係。
這篇文章是我嘗試描述如何讓設計文件變得出色。
本文分為 4 個部分：
- 為什麼要編寫設計文件
- 設計文件中應包含哪些內容
- 如何編寫
- 圍繞它的程序
為什麼要編寫設計文件？
設計文件（也稱為技術規範）是關於您計劃如何解決問題的描述。
已經有很多文章解釋了為什麼在開始編碼之前編寫設計文件很重要。所以我在這裡想說的是：
設計文件是確保正確完成工作的最有用的工具。
設計文件的主要目標是透過迫使您仔細思考設計並收集他人的反饋來提高您的效率。人們通常認為設計文件的目的是向其他人傳授某個系統或作為以後的文件。雖然這些可能是有益的副作用，但它們本身並不是目標。
一般來說，如果你正在從事的專案可能需要 1 個工程師月或更長時間，那麼你應該編寫一份設計文件。但不要止步於此——許多較小的專案也可以從迷你設計文件中受益。
太棒了！如果你還在讀這篇文章，那說明你相信設計文件的重要性。然而，不同的工程團隊，甚至同一團隊的工程師，編寫的設計文件往往大不相同。所以讓我們來談談一份好的設計文件的內容、風格和流程。
設計文件中應包括哪些內容？
設計文件描述了問題的解決方案。由於每個問題的性質不同，您自然會希望以不同的方式構建設計文件。
首先，以下是您至少應該考慮 在下一個設計文件中包含的部分列表：
頭銜和人物
您的設計文件的標題、 作者（應與計劃從事該專案的人員名單相同）、 文件的審閱者（我們將在下面的流程部分詳細討論）以及本文件的最後更新日期。
概述
公司每位工程師都應該理解並使用它來確定閱讀文件其餘部分是否有用的高度概括的摘要。摘要最多應為 3 段。
語境
手頭問題的描述、為什麼這個專案是必要的、人們需要知道什麼來評估這個專案，以及它如何適應技術戰略、產品戰略或團隊的季度目標。
目標和非目標
目標部分應該：
描述專案對使用者的影響——你的使用者可能是另一個工程團隊，甚至是另一個技術系統
指定如何使用指標來衡量成功——如果您可以連結到跟蹤這些指標的儀表板，則可以獲得加分
非目標同樣重要，它描述了您不會解決哪些問題，以便每個人都達成共識。
里程碑
一份可衡量的檢查點列表，以便您的 PM 和經理的經理可以瀏覽並大致瞭解專案不同部分的完成時間。如果專案持續時間超過 1 個月，我建議您將專案分解為面向使用者的主要里程碑。
使用日曆日期，這樣您就可以考慮不相關的延遲、假期、會議等。它應該看起來像這樣：
Start Date: June 7, 2018Milestone 1 — New system MVP running in dark-mode: June 28, 2018Milestone 2 - Retire old system: July 4th, 2018End Date: Add feature X, Y, Z to new system: July 14th, 2018
如果某些里程碑的預計到達時間 (ETA) 發生變化，請在此處新增一個[Update]小節，以便利益相關者可以輕鬆看到最新的估計值。
現有解決方案
除了描述當前的實現之外，您還應該透過高階示例流程來說明使用者如何與該系統互動和/或資料如何流經該系統。
使用者故事是構建這一點的好方法。請記住，您的系統可能擁有不同型別的使用者，並且使用情況也不同。
建議的解決方案
有些人將其稱為技術架構部分。再次嘗試透過使用者故事來具體化這一點。可以隨意新增許多子部分和圖表。
首先提供一幅大圖景，然後填寫大量細節。目標是，您可以寫出這樣的世界，然後在某個荒島上度假，團隊中的另一位工程師只需閱讀它並按照您描述的方式實施解決方案即可。
替代解決方案
在提出上述解決方案時，您還考慮了什麼？替代方案的優缺點是什麼？您是否考慮過購買第三方解決方案（或使用開源解決方案）來解決這個問題，而不是自己構建？
可測試性、監控和警報
我喜歡加入這一部分，因為人們經常把它當作事後才想到的東西，或者完全跳過它，而當事情發生故障而他們不知道原因和原因時，它幾乎總是會回來困擾他們。
跨團隊影響
這將如何增加值班和開發運營的負擔？這將花費多少錢？它會導致系統延遲迴歸嗎？它會暴露任何安全漏洞嗎？有哪些負面後果和副作用？支援團隊如何將此事傳達給客戶？
未決問題
您不確定的任何未決問題、您希望讀者參與的有爭議的決定、建議的未來工作等等。此部分的一個俏皮名稱是“已知的未知數”。
詳細範圍和時間表
本節主要供從事該專案的工程師、他們的技術主管和經理閱讀。因此本節位於文件的末尾。
本質上，這是您計劃如何以及何時執行專案每個部分的細分。要準確確定範圍，需要做很多工作，因此您可以閱讀這篇文章以瞭解有關範圍的更多資訊。
我還傾向於將設計文件的這一部分視為正在進行的專案任務跟蹤器，因此每當我的範圍估算發生變化時，我都會更新它。但這更多的是個人喜好。
如何編寫
既然我們已經討論了好的設計文件應該包含哪些內容，那麼讓我們來談談寫作風格。我保證這與你的高中英語課不同。
寫得儘可能簡單
不要試影像你讀過的學術論文那樣寫作。它們是為了給期刊審稿人留下深刻印象而寫的。你的文件是為了描述你的解決方案並獲得隊友的反饋而寫的。你可以使用以下方法獲得清晰度：
- 簡單的話
- 短句
- 專案符號列表和/或編號列表
- 具體的例子，例如“使用者 Alice 連線了她的銀行賬戶，然後...”
新增大量圖表
圖表通常可用於比較多個潛在選項，並且圖表通常比文字更容易解析。我使用 Google Drawing 建立圖表時運氣不錯。
專業提示：請記住在螢幕截圖下方新增指向圖表可編輯版本的連結，以便當情況不可避免地發生變化時，您可以輕鬆地更新它。
包括 數字
問題的規模通常決定了解決方案。為了幫助審閱者瞭解世界狀況，請包含實際數字，例如資料庫行數、使用者錯誤數、延遲 — 以及這些數字如何隨使用量而變化。還記得 Big-O 符號嗎？
嘗試變得有趣
規範不是學術論文。此外，人們喜歡閱讀有趣的東西，所以這是吸引讀者的好方法。不過，不要過度使用，以免偏離核心思想。
如果你和我一樣，很難幽默，Joel Spolsky（顯然以喜劇天賦而聞名……）有這個建議：
最簡單的搞笑方式之一就是在不需要時具體化[… 例如：] 不要說“特殊利益”，而要說“左撇子鱷梨農民”。
進行懷疑論者測試
在將您的設計文件傳送給其他人進行審閱之前，請假裝自己是審閱者，仔細閱讀一下。您對這個設計可能有什麼問題和疑慮？然後先發制人地解決它們。
進行假期測試
如果您現在去度長假並且沒有網際網路接入，您的團隊中的某個人可以閱讀文件並按照您的意圖實施它嗎？
設計文件的主要目標不是知識共享，但這是一種評估清晰度的好方法，以便其他人可以真正給你有用的反饋。
過程
設計文件可幫助您在浪費大量時間實施錯誤的解決方案或錯誤問題的解決方案之前獲得反饋。獲得良好反饋有很多技巧，但那是以後的文章的內容。現在，我們只具體討論如何編寫設計文件並獲得反饋。
首先，參與該專案的每個人都應該參與設計過程。如果技術主管最終推動了很多決策，那也沒關係，但每個人都應該參與討論並認同設計。因此，本文中的“你”實際上是複數的“你”，包括專案中的所有人。
其次，設計過程並不意味著你要盯著白板理論化想法。你可以自由地動手，為潛在的解決方案製作原型。這與在編寫設計文件之前開始為專案編寫生產程式碼不同。不要那樣做。但你絕對應該自由地編寫一些粗製濫造的一次性程式碼來驗證一個想法。為了確保你只編寫探索性程式碼，請制定一條規則，即這些原型程式碼都不會合併到 master 中。
此後，當您開始對如何開展專案有了一些想法時，請執行以下操作：
- 請團隊中經驗豐富的工程師或技術主管擔任審閱者。理想情況下，此人應受人尊敬和/或熟悉問題的邊緣情況。如有必要，可以用珍珠奶茶賄賂他們。
- 走進一間帶著白板的會議室。
- 向這位工程師描述你正在解決的問題（這是一個非常重要的步驟，不要跳過！）。
- 然後解釋您所想的實施方案，並說服他們這是正確的做法。
在開始編寫設計文件之前完成所有這些工作，可以讓您儘快獲得反饋，而無需投入更多時間並執著於任何特定解決方案。通常，即使實現保持不變，您的審閱者也能夠指出您需要涵蓋的極端情況，指出任何潛在的混淆區域，並預測您以後可能遇到的困難。
然後，在您編寫完設計文件的草稿後，請同一位審閱者再次通讀一遍，並在設計文件的標題和人員部分新增其姓名作為審閱者，以蓋章批准。這為審閱者創造了額外的激勵和責任。
在這方面，考慮針對設計的特定方面新增專門的審閱人員（例如 SRE 和安全工程師）。
在您和審閱者簽字同意後，請隨時將設計文件傳送給您的團隊，以獲取更多反饋和知識共享。我建議將此反饋收集過程的時間限制在 1 周左右，以避免長時間延誤。承諾在那一週內解決人們留下的所有問題和評論。留下評論 = 壞運氣。
最後，如果您、審閱者和其他閱讀文件的工程師之間存在很多爭議，我強烈建議將所有爭議點彙總到文件的討論部分。然後，與各方安排一次會議，親自討論這些分歧。
當討論主題超過 5 條評論時，進行面對面討論往往更有效率。請記住，即使每個人都無法達成共識，您仍有責任做出最終決定。
最近，在與Shrey Banga討論此事時，我瞭解到 Quip 也有類似的流程，除了讓團隊中經驗豐富的工程師或技術主管擔任審閱者之外，他們還建議讓其他團隊的工程師審閱文件。我還沒有嘗試過這種方法，但我確實認為這有助於從具有不同觀點的人那裡獲得反饋，並提高文件的整體可讀性。
完成上述所有操作後，就可以開始實施了！為了獲得額外的加分，請在實施設計時將此設計文件視為一份活文件。每次您瞭解到導致您更改原始解決方案或更新範圍的內容時，請更新文件。當您不必向所有利益相關者一遍又一遍地解釋事情時，您會感謝我的。
最後，讓我們真正地討論一下：我們如何評估設計文件的成功？
我的同事Kent Rakip對此有一個很好的答案：如果工作的投資回報率正確，設計文件就是成功的。這意味著成功的設計文件實際上可能會產生這樣的結果：
- 你花了 5 天時間編寫設計文件，這迫使你思考技術架構的不同部分
- 你從審閱者那裡得到的反饋X是所提議的架構中最危險的部分
- 您決定首先實施X以降低專案風險
- 三天後，你發現這X是不可能的，或者比你最初設想的要困難得多
- 你決定停止這個專案，轉而優先處理其他工作
在本文開頭，我們說過設計文件的目的是確保完成正確的工作。在上面的例子中，多虧了這份設計文件，您才只花了 8 天時間，而不是浪費幾個月的時間，然後放棄這個專案。在我看來，這似乎是一個相當成功的結果。
您被新增為規範的審閱者，您應該做什麼？
我的好朋友兼榜樣Joy有以下很好的建議：
當您簽署規範時，您應該瞭解以下問題的答案。
專案
- 這個專案解決了什麼問題？我們如何知道它是否成功？
元
- 這個專案正在做出的重大決策是什麼？其影響是什麼？
- 專案中最複雜或風險最大的部分是什麼？如何處理？
技術設計
- 您在 5 分鐘內能想到的最簡單的替代實現是什麼？相對於此，所提議的方法有哪些優點/缺點？所提議方法中的額外實現時間能帶來哪些改進？值得嗎？注意：這並不意味著您將在 5 分鐘內想出更好的方法。它只是為您提供一些更具體的東西來與所提議的實現進行比較。
- 這個專案的關鍵技術決策是什麼？這些決策的結果是怎樣的？
- 該專案與哪些外部系統互動？它增加了多少規模？它是否遵循當前的最佳實踐和模式？它是否符合長期發展方向？它是否意味著未來的承諾或技術債務？
- 您知道哪些資訊，而作者可能不知道？您之前見過類似的解決方案嗎？（成功與否）他們使用的系統中是否存在不明顯的邊緣情況？是否存在您認為實際上需要一段時間的“簡單”實現？
監控/警報
- 專案期間最可能出現的故障模式是什麼（例如中期推出）
- 專案結束後最有可能的失敗模式是什麼？
- 上述情況將如何監控和檢測？