作為一名軟件工程師，我花了很多時間閱讀和編寫設計文檔。在完成了數百篇這些文檔之后，我親眼目睹了優秀設計文檔與項目最終成功之間的強烈關聯。
本文試圖描述使設計文檔變得更好的原因。
本文分為4個部分：
- 為什么要寫一份設計文件
- 什么在設計文檔，包括
- 怎么寫
- 圍繞它的過程
為什么要寫一個設計文件？
設計文檔 - 也稱為技術規范 - 描述了您計划如何解決問題。
關於為什么在進入編碼之前編寫設計文檔很重要的原因已經有很多文章。所以我在這里說的是：
設計文檔是確保正確工作完成的最有用工具。
設計文檔的主要目標是通過強迫您思考設計並收集其他人的反饋來提高您的效率。人們通常認為設計文檔的目的是教會其他人關於某個系統或稍后作為文檔。雖然這些可能是有益的副作用，但它們本身並不是目標。
作為一般的經驗法則，如果您正在處理可能需要1個工程師月或更長時間的項目，那么您應該編寫設計文檔。但不要止步於此 - 許多小型項目也可以從迷你設計文檔中受益。
大！如果您還在閱讀，您會相信設計文檔的重要性。但是，不同的工程團隊，甚至同一團隊的工程師，經常以不同的方式編寫設計文檔。讓我們來談談優秀設計文檔的內容，風格和流程。
在設計文檔中包含哪些內容？
設計文檔描述了問題的解決方案。由於每個問題的性質不同，您自然希望以不同的方式構建您的設計文檔。
首先，以下是您應該至少考慮 在下一個設計文檔中包含的部分列表：
標題和人物
您的設計文檔的標題， 作者（應該與計划參與此項目的人員列表相同），文檔的審閱者（我們將在“處理”部分中詳細討論）下面），以及本文檔最后更新的日期。
概觀
高級摘要，公司的每位工程師都應該理解並使用它來決定是否有必要閱讀其余的文檔。最多應為3段。
上下文
對手頭問題的描述，為什么這個項目是必要的，人們需要知道什么來評估這個項目，以及它如何適應技術戰略，產品戰略或團隊的季度目標。
目標和非目標
目標部分應：
- 描述項目的用戶驅動影響 - 您的用戶可能是另一個工程團隊甚至是另一個技術系統
- 指定如何使用指標衡量成功 - 如果您可以鏈接到跟蹤這些指標的儀表板，則可以獲得獎勵積分
非目標對於描述您不會修復哪些問題同樣重要，因此每個人都在同一頁面上。
里程碑
一個可衡量的檢查點列表，因此您的PM和您的經理的經理可以瀏覽它並大致了解項目的不同部分何時完成。如果項目超過1個月，我建議您將項目分解為面向用戶的主要里程碑。
使用日歷日期，以便考慮無關的延遲，假期，會議等。它應該看起來像這樣：
Start Date: June 7, 2018
Milestone 1 — New system MVP running in dark-mode: June 28, 2018
Milestone 2 - Retire old system: July 4th, 2018
End Date: Add feature X, Y, Z to new system: July 14th, 2018
[Update]如果其中一些里程碑的ETA發生變化，請在此處添加一個小節，以便利益相關者可以輕松查看最新的估算值。
現有解決方案
除了描述當前的實現之外，您還應該通過一個高級示例流來說明用戶如何與此系統交互和/或數據如何通過它。
一個用戶故事是這個框架的好方法。請記住，您的系統可能包含具有不同用例的不同類型的用戶。
提出的解決方案
有些人稱之為技術架構部分。再次，嘗試通過用戶故事來具體化這一點。隨意包含許多子部分和圖表。
首先提供一個大的圖片，然后填寫大量 的 細節。瞄准一個你可以寫這個的世界，然后在一個荒島上度假，團隊中的另一位工程師可以閱讀它並按照你的描述實施解決方案。
替代方案
在提出上述解決方案時，您還考慮了什么？替代品的優點和缺點是什么？您是否考慮購買第三方解決方案 - 或使用開源解決方案 - 解決此問題而不是構建自己的問題？
可測試性，監控和警報
我喜歡包括這一部分，因為人們經常把它視為事后的想法或者一起跳過它們，而且當事情破裂並且他們不知道如何或為什么時，它幾乎總會回來咬它們。
跨團隊影響力
如何增加電話和開發負擔？
它需要多少錢？
它是否會導致系統出現任何延遲回歸？
它是否暴露了任何安全漏洞？
有什么負面后果和副作用？
支持團隊如何與客戶溝通？
打開問題
任何你不確定的未解決的問題，你想讓讀者權衡的有爭議的決定，建議未來的工作，等等。這部分的一個詼諧的名字是“已知的未知數”。
詳細的范圍和時間表
本節主要是由參與該項目的工程師，他們的技術主管和他們的經理閱讀。因此，本節在文檔的最后。
從本質上講，這是您計划執行項目的每個部分的方式和時間的細分。有很多內容可以准確地確定范圍，因此您可以閱讀此文章以了解有關范圍界定的更多信息。
我傾向於將設計文檔的這一部分視為正在進行的項目任務跟蹤器，因此每當我的范圍估計發生變化時，我都會對此進行更新。但這更多的是個人偏好。
怎么寫
現在，我們已經談了什么進入一個好的設計文檔，讓我們來談談寫作風格。我保證這與你的高中英語課不同。
寫得盡可能簡單
不要試着像你讀過的學術論文那樣寫作。它們是為了給期刊評論家留下深刻印象。您的文檔是為了描述您的解決方案並從您的隊友那里獲得反饋而編寫的。您可以通過以下方式實現清晰：
- 簡單的話
- 短句
- 項目符號列表和/或編號列表
- 具體的例子，如“用戶愛麗絲連接她的銀行帳戶，然后......”
添加大量圖表和圖表
圖表通常可用於比較幾個可能的選項，圖表通常比文本更容易解析。我已經用Google Drawing創建圖表了。
專業提示：請記住在屏幕截圖下添加指向圖表的可編輯版本的鏈接，以便您可以在以后不可避免地發生變化時輕松更新。
包括 數字
問題的規模通常決定了解決方案。為了幫助審閱者了解世界狀況，請包括實際數字，例如數據庫行數，用戶錯誤數，延遲數以及這些數據如何隨着使用情況而擴展。還記得你的Big-O符號嗎？
試着變得有趣
規范不是學術論文。此外，人們喜歡閱讀有趣的東西，所以這是讓讀者保持參與的好方法。盡管如此，不要過分誇大核心思想。
如果你和我一樣，很難搞笑，Joel Spolsky（顯然以他的喜劇天賦而聞名......）有這樣的提示：
有趣的最簡單的方法之一就是在沒有被 要求時具體說明 [......例子：]而不是說“特殊利益”，而是說“左撇子avacado農民”。
進行懷疑測試
在將您的設計文檔發送給其他人進行審核之前，請假裝成為審核人員。您對此設計有什么疑問和疑問？然后先發制人地解決它們。
做假期測試
如果您現在無法訪問互聯網，那么您團隊中的某個人是否可以閱讀該文檔並按照您的意圖實施該文檔？
設計文檔的主要目標不是知識共享，但這是一種評估清晰度的好方法，以便其他人可以實際為您提供有用的反饋。
處理
啊，是可怕的P字。設計文檔可幫助您在浪費大量時間實施錯誤解決方案或解決錯誤問題之前獲得反饋。獲得良好反饋有很多藝術，但這是后來的文章。現在，讓我們專門討論如何編寫設計文檔並獲取反饋。
首先，參與項目的每個人都應該參與設計過程。如果技術主管最終決定做出很多決定，那也沒關系，但是每個人都應該參與討論並購買設計。因此，本文中的“你”是一個真正的復數“你”，其中包括項目中的所有人。
其次，設計過程並不意味着你盯着白板理論化的想法。隨意將您的手弄臟並制作潛在的解決方案原型。這與在編寫設計文檔之前開始為項目編寫生產代碼不同。不要那樣做。但你絕對應該隨意寫一些hacky一次性代碼來驗證一個想法。為了確保您只編寫探索性代碼，請將此原型代碼中的任何一個都合並為master。
之后，當您開始了解如何進行項目時，請執行以下操作：
- 請您團隊中經驗豐富的工程師或技術負責人成為您的評審員。理想情況下，這將是一個受到良好尊重和/或熟悉問題邊緣情況的人。如有必要，用boba賄賂他們。
- 進入帶白板的會議室。
- 描述你正在向這位工程師解決的問題（這是非常重要的一步，不要跳過它！）。
- 然后解釋你想到的實現，並說服他們這是正確的構建。
在開始編寫設計文檔之前完成所有這些操作可以讓您在投入更多時間並接受任何特定解決方案之前盡快獲得反饋。通常情況下，即使實施保持不變，您的審核人員也可以指出您需要覆蓋的極端案例，指出任何可能的混淆區域，並預測您以后可能遇到的困難。
然后，在您撰寫了設計文檔的粗略草稿后，讓相同的審閱者再次閱讀，並通過在設計文檔的“ 標題和人物”部分中添加他們的名稱作為審閱者來標記它。這為審閱者創造了額外的激勵和責任。
在這方面，考慮為設計的特定方面添加專門的審閱者（例如SRE和安全工程師）。
一旦您和審核人員簽字，請隨時將設計文檔發送給您的團隊，以獲得更多反饋和知識共享。我建議將反饋收集過程限時約1周，以避免延誤。致力於解決人們在該周內留下的所有問題和評論。留下評論懸掛=壞業力。
最后，如果您，您的審閱者和其他閱讀該文檔的工程師之間存在很多爭議，我強烈建議您在文檔的“ 討論”部分中合並所有爭用點。然后，與各方召開會議，親自談論這些分歧。
每當討論主題長度超過5條評論時，轉向親自討論往往會更有效率。請記住，即使每個人都無法達成共識，您仍然有責任進行最后的通話。
在最近與Shrey Banga談論此事時，我了解到Quip有一個類似的過程，除了作為審閱者在您的團隊中擁有經驗豐富的工程師或技術負責人之外，他們還建議讓不同團隊的工程師審核該文檔。我沒有試過這個，但我當然可以看到這有助於從不同角度的人那里獲得反饋，並提高文檔的一般可讀性。
完成上述所有操作后，即可開始實施！對於額外的布朗尼點，在實施設計時將此設計文檔視為活文檔。每當您了解到導致您更改原始解決方案或更新范圍的內容時，請更新文檔。如果您不必一遍又一遍地向所有利益相關者解釋，您會感謝我。
最后，讓我們真正了解一下：我們如何評估設計文檔的成功？
我的同事Kent Rakip對此有一個很好的答案：如果完成正確的投資回報率，設計文檔就會成功。這意味着成功的設計文檔實際上可能導致這樣的結果：
- 您花了5天時間編寫設計文檔，這迫使您通過技術架構的不同部分進行思考
- 您可以從審閱者那里獲得反饋，這
X是建議架構中最具風險的部分 - 您決定先實施
X以降低項目風險 - 3天后，你發現這
X是不可能的，或者比你原先預期的要困難得多 - 您決定停止處理此項目並優先考慮其他工作
在本文開頭，我們說設計文檔的目標是確保正確的工作完成。在上面的示例中，由於這個設計文檔，您可能只花了8天時間，而不是浪費可能幾個月才能中止此項目。對我來說似乎是一個非常成功的結果。
如果您有任何問題或反饋，請在下面留言！我也很想知道你如何在團隊中以不同的方式設計文檔。
