設計文檔應該怎麼寫？

作為一名軟體工程師，如何寫好一份優秀的設計文檔，是十分重要的。

本文試圖描述如何才能寫好一份設計文檔。

本文分為4個部分：

• 為什麼要寫一份設計文檔
• 要包含在設計文檔中的内容
• 怎麼寫
• 相關過程

為什麼要寫一個設計文檔？

    設計是軟體過程的一個重要環節。而設計文檔的編寫，更是設計階段的重要産物。設計文檔也被業界人士認為是技術規範，描述是如何解決或實作需求中内容，最終于願景達成最終一緻性的比較檔案。設計文檔是確定正确完成工作的最有用工具。

設計文檔中應該包含哪些内容？

設計文檔描述了問題的解決方案。由于每個問題的性質不同，您自然希望以不同的方式建構您的設計文檔。

首先，以下是您應該至少考慮在下一個設計文檔中包含的部分清單：

标題和參與者

您的設計文檔的标題，作者（應該與計劃參與此項目的人員清單相同），檢查者（我們将在“處理”部分中詳細讨論），以及最後更新日期。

概覽

高度概括的，公司的每位工程師都應該了解并能夠通過閱讀概覽來決定是否有必要閱讀其餘的文檔。最多3段。

背景

對手頭問題的描述，為什麼這個項目是必要的，人們需要知道什麼來評估這個項目，以及它如何适應技術戰略，産品戰略或團隊的季度目标。

目标和非目标

目标部分應包括：

描述項目的使用者驅動影響 - 您的使用者可能是另一個工程團隊甚至是另一個技術系統

指定如何使用名額衡量成功 - 如果您可以連結到跟蹤這些名額的儀表闆，則可以獲得獎勵

非目标同樣重要，它描述了您不會修複哪些問題，是以它也和目标在同一頁面上。

裡程碑

一個可衡量的檢查點清單，是以您的PM和您的經理的經理可以浏覽它并大緻了解項目的不同部分何時完成。如果項目超過1個月，我建議您将項目分解為面向使用者的主要裡程碑。

使用月曆日期，以便考慮無關的延遲，假期，會議等。它應該看起來像這樣：

開始日期：2018年6月7日

裡程碑1 - 以暗模式運作的新系統MVP：2018年6月28日

裡程碑2 - 下掉舊系統：2018年7月4日

結束日期：将功能X，Y，Z添加到新系統：2018年7月14日

如果其中一些裡程碑的ETA發生變化，請在此處添加[更新]子部分，以便相關方可以輕松檢視最新的情況。

目前解決方案

除了描述目前的實作之外，您還應該通過一個進階示例流來說明使用者如何與此系統互動和/或資料如何通過它。

使用者故事是建構此架構的絕佳方式。請記住，您的系統可能包含具有不同用例的不同類型的使用者。

推薦解決方案

有人稱之為技術架構部分。再次，嘗試通過使用者故事來具體化這一點。可以包含許多子部分和圖表。

先提供一張大圖，然後填寫大量細節，確定即使你出去度假了，團隊中的另一位工程師也可以閱讀它并按照你的描述實施解決方案。

替代方案

在提出上述解決方案時，您還考慮了什麼？替代品的優點和缺點是什麼？您是否考慮購買第三方解決方案 - 或使用開源解決方案 - 解決此問題而不是建構自己的問題？

監控和警報

我喜歡包括這一部分，因為人們經常事後才去考慮它們或者幹脆忽略它們，當事情出了岔子，他們一籌莫展。

跨團隊配合方面

是否會增加外呼和開發團隊的負擔？

它會花多少錢？

它是否會導緻系統延遲？

它是否暴露了安全漏洞？

有什麼負面後果和副作用？

支援團隊如何與客戶溝通？

讨論

任何你不确定的公開問題，你想讓讀者權衡的有争議的決定，建議未來的工作，等等。

詳細的範圍和時間表

本節主要是由參與該項目的工程師，他們的技術主管和他們的經理閱讀。是以，本節在文檔的最後。

從本質上講，這是您計劃執行項目每個部分的方式和時間的細分。有很多内容可以準确地确定範圍，是以您可以閱讀這篇文章以了解有關範圍的更多資訊。

我傾向于将設計文檔的這一部分視為正在進行的項目任務跟蹤器，是以每當我的範圍估計發生變化時，我都會更新它。但這更多的是個人偏好。

怎麼寫

下面讓我們來談談寫作風格。我保證這與你的高中英語課不同。

寫得盡可能簡單

不要試着寫你讀過的學術論文。它們是為了給期刊評論家留下深刻印象。您的文檔是為了描述您的解決方案并從您的隊友那裡獲得回報而編寫的。多運用類似這些：

• 簡單的話
• 短句
• 項目符号清單和/或編号清單
• 具體的例子，如“使用者愛麗絲連接配接她的銀行賬戶，然後…”

添加大量表格和圖示

表格通常可用于比較幾個可能的選項，圖表通常比文本更容易解讀。我已經用Google Drawing建立圖表了。

專業提示：請記住在螢幕截圖下添加指向圖表的可編輯版本的連結，以便以後在事情不可避免地發生變化時輕松更新。

包括數字

問題嚴重程度通常決定了解決方案。為了幫助審閱者了解實際狀況，請包括實際數字，如資料庫行數，使用者錯誤數，延遲 - 以及這些資料如何随着使用情況而擴充（請記住您的Big-O表示法？）。

試着變得有趣

規範不是學術論文。此外，人們喜歡閱讀有趣的東西，是以這是讓讀者保持參與的好方法。盡管如此，不要喧賓奪主。

進行測試

在将設計文檔發送給其他人進行稽核之前，請自己作為稽核人員過一遍。您對此設計有什麼疑問？然後先發制人地解決它們。

做假期測試

如果您現在無法通路網際網路，那麼您團隊中的某個人是否可以閱讀該文檔并按照您的意圖實施該文檔？

設計文檔的主要目标不是知識共享，但這是一種評估清晰度的好方法，以便其他人可以實際為您提供有用的回報。

處理

設計文檔可幫助您在浪費大量時間實施錯誤解決方案或解決錯誤問題之前獲得回報。獲得良好回報有很多藝術，但這是以後的事。現在，讓我們專門讨論如何編寫設計文檔并擷取回報。

首先，參與項目的每個人都應該參與設計過程。如果技術主管最終推動了很多決定，那也沒關系，但是每個人都應該參與讨論并參與設計。是以，本文中的“你”是一個真正的複數“你”，包括項目中的所有人。

其次，設計過程并不意味着你盯着白闆寫些理論化的想法，随意制作潛在的解決方案原型。這與在編寫設計文檔之前開始為項目編寫生産代碼不同，不要那樣做。但你絕對應該随意寫一些一次性代碼來驗證想法。

之後，當您開始了解如何進行項目時，請執行以下操作：

1. 請您團隊中經驗豐富的工程師或技術負責人成為您的評審員。理想情況下，這将是一個受到尊重和/或熟悉問題細節的人。
2. 進入帶白闆的會議室。
3. 向這位工程師描述你正在解決的問題（這是非常重要的一步，不要跳過它！）。
4. 然後解釋你想到的實作，并說服他們這是正确的建構。

在開始編寫設計文檔之前完成所有這些操作可以讓您在投入更多時間并接受任何特定解決方案之前盡快獲得回報。通常情況下，即使實施保持不變，您的稽核員也可以指出您需要覆寫的極端案例，指出任何潛在的混淆區域，并預測您以後可能遇到的困難。

然後，在您撰寫了設計文檔的粗略草稿之後，讓相同的審閱者再次閱讀它，并通過在設計文檔的“标題和人物”部分中添加他們的名稱作為審閱者來标記它。這為審閱者創造了額外的激勵和責任。

在這方面，考慮為設計的特定方面添加專門的審閱者（例如SRE和安全工程師）。

一旦您和稽核人員确定了，請随時将設計文檔發送給您的團隊，以獲得額外的回報和知識共享。我建議将回報收集過程的時間限制在1周左右，以避免延誤。緻力于解決人們在該周内留下的所有問題和評論。

最後，如果您，您的審閱者和其他閱讀該文檔的工程師之間存在很多争議，我強烈建議您在文檔的“讨論”部分中合并所有争議點。然後，與各方召開會議，當面談論這些分歧。

每當讨論主題長度超過5條評論時，轉向當面讨論往往效率更高。請記住，即使每個人都無法達成共識，您仍然有責任進行最後的溝通。

在最近與Shrey Banga談論此事時，我了解到Quip有一個類似的過程，除了在您的團隊中擁有經驗豐富的工程師或技術負責人作為審閱者之外，他們還建議讓不同團隊的工程師稽核該文檔。我沒有嘗試過這個，但我當然可以看到這有助于從不同角度的人那裡獲得回報，并提高文檔的一般可讀性。

完成上述所有操作後，即可開始實施！對于額外的布朗尼點，在實施設計時将此設計文檔視為活文檔。每次您更改原始解決方案或更新範圍的内容時，請更新文檔。這樣你就不必向所有利益相關者反複解釋事情，你會感謝我的。

最後，讓我們真正了解一下：我們如何評估設計文檔的成功？

我的同僚Kent Rakip對此有一個很好的答案：如果完成正确的投資回報率，設計文檔就會成功。這意味着成功的設計文檔實際上可能導緻這樣的結果：

1. 您花了5天時間編寫設計文檔，這迫使您通過技術架構的不同部分進行思考
2. 您可以從審閱者那裡獲得回報，即X是建議架構中最具風險的部分
3. 您決定首先實施X以降低項目風險
4. 3天後，你發現X要麼不可能，要麼比你原先想要的要困難得多
5. 您決定停止處理此項目并優先處理其他工作

在本文開頭，我們說設計文檔的目标是確定正确的工作完成。 在上面的示例中，由于這個設計文檔，您可能隻花了8天時間而不是浪費幾個月才能中止此項目。 對我來說似乎是一個非常成功的結果。

本文由網易雲社群簡譯，更多詳情請參見原文。

原文位址