【譯】如何寫出一份優秀的軟件設計文檔

做爲一名軟件工程師，我花了不少時間閱讀和編寫設計文檔。在完成了數百篇這些文檔以後，我親眼目擊了優秀設計文檔與項目最終成功之間的強烈關聯。

本文試圖描述什麼使設計文檔變得更好。

本文分爲4個部分：

爲何要寫一份設計文檔

要包含在設計文檔中的內容

怎麼寫

相關過程

爲何要寫一個設計文檔？
設計文檔 - 也稱爲技術規範 - 描述了您計劃如何解決問題。

已經有不少文章闡述過爲何在開工以前編寫設計文檔很重要。因此我在這裏要說的是：

設計文檔是確保正確完成工做的最有用工具。

設計文檔的主要目標是經過強迫您思考設計並收集其餘人的反饋來提升您的效率。人們一般認爲設計文檔的目的是教會其餘人關於某個系統或稍後做爲文檔。雖然這些多是一部分做用，但它們並非最根本的目的。

做爲通常經驗法則，若是您正在處理可能須要1個工程師月或更長時間的項目，那麼您應該編寫設計文檔。但不要止步於此 - 許多小型項目也能夠從迷你設計文檔中受益。

若是您還在閱讀，您會相信設計文檔的重要性。可是，不一樣的研發團隊，甚至同一團隊的工程師，常常以很是不一樣的方式編寫設計文檔。讓咱們來談談優秀設計文檔的內容，風格和寫做流程吧。

設計文檔中應該包含哪些內容？
設計文檔描述了問題的解決方案。因爲每一個問題的性質不一樣，您天然但願以不一樣的方式構建您的設計文檔。

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

標題和參與者
您的設計文檔的標題，做者（應該與計劃參與此項目的人員列表相同），檢查者（咱們將在「處理」部分中詳細討論），以及最後更新日期。

概覽
高度歸納的，公司的每位工程師都應該理解並可以經過閱讀概覽來決定是否有必要閱讀其他的文檔。最多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表示法？）。

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

進行測試
在將設計文檔發送給其餘人進行審覈以前，請本身做爲審覈人員過一遍。您對此設計有什麼疑問？而後先發制人地解決它們。

作假期測試
若是您如今沒法訪問互聯網，那麼您團隊中的某我的是否能夠閱讀該文檔並按照您的意圖實施該文檔？

設計文檔的主要目標不是知識共享，但這是一種評估清晰度的好方法，以便其餘人能夠實際爲您提供有用的反饋。

處理
設計文檔可幫助您在浪費大量時間實施錯誤解決方案或解決錯誤問題以前得到反饋。得到良好反饋有不少藝術，但這是之後的事。如今，讓咱們專門討論如何編寫設計文檔並獲取反饋。

首先，參與項目的每一個人都應該參與設計過程。若是技術主管最終推進了不少決定，那也不要緊，可是每一個人都應該參與討論並參與設計。所以，本文中的「你」是一個真正的複數「你」，包括項目中的全部人。

其次，設計過程並不意味着你盯着白板寫些理論化的想法，隨意製做潛在的解決方案原型。這與在編寫設計文檔以前開始爲項目編寫生產代碼不一樣，不要那樣作。但你絕對應該隨意寫一些一次性代碼來驗證想法。

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

請您團隊中經驗豐富的工程師或技術負責人成爲您的評審員。理想狀況下，這將是一個受到尊重和/或熟悉問題細節的人。

進入帶白板的會議室。

向這位工程師描述你正在解決的問題（這是很是重要的一步，不要跳過它！）。

而後解釋你想到的實現，並說服他們這是正確的構建。

在開始編寫設計文檔以前完成全部這些操做可讓您在投入更多時間並接受任何特定解決方案以前儘快得到反饋。一般狀況下，即便實施保持不變，您的審覈員也能夠指出您須要覆蓋的極端案例，指出任何潛在的混淆區域，並預測您之後可能遇到的困難。

而後，在您撰寫了設計文檔的粗略草稿以後，讓相同的審閱者再次閱讀它，並經過在設計文檔的「標題和人物」部分中添加他們的名稱做爲審閱者來標記它。這爲審閱者創造了額外的激勵和責任。

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

一旦您和審覈人員肯定了，請隨時將設計文檔發送給您的團隊，以得到額外的反饋和知識共享。我建議將反饋收集過程的時間限制在1周左右，以免延誤。致力於解決人們在該周內留下的全部問題和評論。

最後，若是您，您的審閱者和其餘閱讀該文檔的工程師之間存在不少爭議，我強烈建議您在文檔的「討論」部分中合併全部爭議點。而後，與各方召開會議，當面談論這些分歧。

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

在最近與Shrey Banga談論此事時，我瞭解到Quip有一個相似的過程，除了在您的團隊中擁有經驗豐富的工程師或技術負責人做爲審閱者以外，他們還建議讓不一樣團隊的工程師審覈該文檔。我沒有嘗試過這個，但我固然能夠看到這有助於從不一樣角度的人那裏得到反饋，並提升文檔的通常可讀性。

完成上述全部操做後，便可開始實施！對於額外的布朗尼點，在實施設計時將此設計文檔視爲活文檔。每次您更改原始解決方案或更新範圍的內容時，請更新文檔。這樣你就沒必要向全部利益相關者反覆解釋事情，你會感謝個人。

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

個人同事Kent Rakip對此有一個很好的答案：若是完成正確的投資回報率，設計文檔就會成功。這意味着成功的設計文檔實際上可能致使這樣的結果：

您花了5天時間編寫設計文檔，這迫使您經過技術架構的不一樣部分進行思考

您能夠從審閱者那裏得到反饋，即X是建議架構中最具風險的部分

您決定首先實施X以下降項目風險

3天后，你發現X要麼不可能，要麼比你原先想要的要困可貴多

您決定中止處理此項目並優先處理其餘工做

在本文開頭，咱們說設計文檔的目標是確保正確的工做完成。 在上面的示例中，因爲這個設計文檔，您可能只花了8天時間而不是浪費幾個月才能停止此項目。 對我來講彷佛是一個很是成功的結果。

若是您喜歡這篇文章，請在Twitter上關注我，瞭解有關工程，流程和後端系統的更多帖子。

原文地址

文章來源： 網易雲社區