軟件設計文檔模板(怎樣才能寫出好的軟件設計文檔？)

作為一名軟件工程師，我花了很多時間閱讀和編寫設計文檔。經(jīng)過上百份文檔的磨練，我發(fā)現(xiàn)優(yōu)秀的設計文檔和項目的成功有著密切的關系。

本文將介紹如何撰寫一份優(yōu)秀的設計文檔。

為什么要寫設計文檔？

文檔也是技術規(guī)范，用來描述你打算如何解決問題。已經(jīng)有很多文章解釋了為什么設計文檔應該寫在編碼之前。這里不再贅述，但我想再補充一點:

設計是確保工作正確完成的最有用的工具。

該文檔的主要目的是迫使您仔細思考設計并收集他人的反饋，以便更好地完成您的工作。一般認為，設計文檔的目的是讓別人了解某個系統(tǒng)，或者作為參考文檔。這些只是設計文檔有益的副作用，但絕不是其根本目的。

根據(jù)經(jīng)驗，如果你的項目需要一個人月或更長時間，那么你應該寫設計文檔。此外，一些小項目也可以受益于迷你設計文件。

但是，不同的工程團隊，甚至是同一個團隊的工程師，寫設計文檔的方式是不一樣的。接下來，我們來談談優(yōu)秀設計文檔的內(nèi)容、風格和流程。

設計中應該包括哪些內(nèi)容？

設計文檔描述了問題的解決方案。因為每個問題的性質(zhì)不同，設計文檔的結構也不同。

這是一份清單。你至少可以考慮在文檔中包含這些內(nèi)容。

頭銜和角色。

文檔的標題、作者(應該與計劃參與項目的人員列表相同)、文檔的審閱者(我們將在“過程”部分詳細討論)以及文檔的最后更新日期。

摘要

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

背景

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

目標和非目標

目標應包括:

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

指定如何使用度量來衡量項目的成功——如果能鏈接到度量儀表板就更好了。

非目標同樣重要。它們用來描述項目解決不了什么問題，讓大家達成共識。

里程碑

一系列可測量的檢查點，通過這些檢查點，你的項目經(jīng)理和你的老板可以大致知道項目的每個部分何時完成。如果項目時間超過1個月，我建議你把它分解成面向用戶的里程碑。

設置里程碑時，可以使用日歷日期，考慮到延誤、節(jié)假日、會議等因素。例如:

開始日期:2018年6月7日

里程碑1-在黑暗模式下運行新系統(tǒng)MVP:2018年6月28日

里程碑2-拋棄舊系統(tǒng):2018年7月4日

End:在新系統(tǒng)中增加新功能X，Y，Z:2018 . 7 . 14

如果其中一些里程碑的ETA發(fā)生了變化，就需要在這里添加【更新】，相關人員可以很容易的看到更新的內(nèi)容。

目前的方案

除了描述當前的實現(xiàn)，還應該舉例說明用戶如何與系統(tǒng)交互以及數(shù)據(jù)如何在系統(tǒng)中流動。

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

擬議方案

有人稱這部分為技術架構。這一部分也可以通過用戶故事來體現(xiàn)，用戶故事可以包含多個子部分和圖表。

從大圖開始，然后補充細節(jié)。確保即使你在荒島上度假，團隊中的其他工程師也能按照你的描述來實現(xiàn)解決方案。

其他選擇

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

以及監(jiān)控和警報

人們往往把這一部分當作事后的想法，甚至直接忽略。但是問題發(fā)生后，他們很著急，卻不知道該怎么辦，也不知道為什么會出現(xiàn)這些問題。

跨團隊影響

這樣會不會增加倒班待機和DevOps的負擔？

它的成本是多少？

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

會不會暴露系統(tǒng)安全漏洞？

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

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

討論

此部分可以包含您不確定的任何問題、您希望閱讀文檔的人一起權衡的有爭議的決定、對未來工作的建議等等。

的詳細范圍和時間表

本部分的主要讀者是參與項目的工程師、技術主管和管理人員。因此，這一部分放在文件的末尾。

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

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

怎樣才能寫好文檔？

談完了一份優(yōu)秀的設計文檔應該包含哪些內(nèi)容，現(xiàn)在來談談寫作風格。

盡可能保持簡單。

不要把設計文檔寫成你讀過的學術論文。論文旨在打動期刊評論家，而設計文檔旨在描述你的解決方案并獲得他人的反饋。您可以通過以下方式使文檔更加清晰:

簡單的詞

使用短句

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

提供具體例子。

添加圖表

圖表很容易比較幾個選項，通常比文本更容易理解。我經(jīng)常使用Google Drawing來創(chuàng)建圖表。

請記得在截圖下方添加圖表源文件的鏈接，以便在圖表發(fā)生變化時進行更新。

包括數(shù)字。

問題的大小通常決定了解決方案的大小。為了更好地幫助審閱者了解情況，請在文檔中使用實際數(shù)字，如數(shù)據(jù)庫行數(shù)、用戶錯誤數(shù)、延遲以及這些數(shù)據(jù)和使用情況之間的關系。(還記得大O記號嗎？)

添加利息

記住，技術規(guī)范不是學術論文。另外，人喜歡看有趣的東西，但不要為了好玩而偏離核心思想。

自我檢查

在將設計文件發(fā)送給其他人審閱之前，假裝成審閱者。你對這份設計文件有什么疑問？然后解決這些問題再發(fā)文件。

假期測試

如果你是獨占性的，不能上網(wǎng)，團隊里的其他人可以看這個文檔，按照你的意圖執(zhí)行里面的內(nèi)容嗎？

文檔設計的主要目的不是分享知識，但它是評估清晰度的好方法，這樣別人可以給你提供有用的反饋。

程序

設計文檔可以幫助你在浪費大量時間實現(xiàn)錯誤的解決方案或解決錯誤的問題之前獲得反饋。獲得好的反饋是一門藝術，但那是另一回事了?，F(xiàn)在，讓我們討論如何獲得設計文檔的反饋。

首先，參與項目的每個人都應該參與設計過程。即使很多決策是技術總監(jiān)做的，也沒關系。至少每個人都應該參與討論并收到他們的設計。

其次，設計過程不一定是盯著白板，在上面畫各種創(chuàng)意。你們可以一起工作來構建各種可能的解決方案原型。這不同于在編寫設計文檔之前編寫代碼。請隨意編寫一些一次性代碼來驗證您的想法。為了確保您的代碼僅用于概念驗證，原型代碼都不能合并到主代碼中。

在您了解如何繼續(xù)進行項目后，請執(zhí)行以下步驟:

請團隊中有經(jīng)驗的工程師或技術負責人審閱您的文檔。理想情況下，評審者應該是一個受人尊敬的人，他已經(jīng)熟悉問題的邊緣情況。

在會議室用白板復習。

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

然后向評審者解釋你想如何實現(xiàn)你的想法，讓他們相信這是正確的解決方案。

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

然后，在你寫好設計文檔的初稿后，請之前的評審人員再讀一遍，并在設計文檔的“標題和人”部分寫上自己的名字，作為對評審人員的鼓勵，也意味著對自己的評審行為負責。

添加審核人姓名時，考慮針對具體問題添加不同的審核人(如SRE和安全工程師)。

審核后，請將設計文檔發(fā)送給您的團隊，以獲得更多反饋。我建議把這個時間限制在一周左右，以免耽誤。盡量在一周內(nèi)解決他們遺留的問題。

最后，如果您與審閱者和其他閱讀本文檔的工程師之間存在爭議，我強烈建議您將這些爭議放在文檔的“討論”部分。然后，與各方召開會議，討論這些差異。

如果一個話題有5條以上的評論，面對面的討論往往效率更高。記住，即使你不能讓所有人都同意，你仍然可以做出決定。

最近和Shrey Banga聊到這個的時候，了解到Quip也有類似的流程，只不過除了讓團隊中有經(jīng)驗的工程師或者技術負責人擔任審核人之外，他們還建議讓不同團隊的工程師來審核設計文檔。我還沒有嘗試過這種方法，但是我確信這將有助于從不同觀點的人那里獲得反饋，從而進一步提高文檔的質(zhì)量。

完成以上所有步驟后，接下來就是開始實施了！在實現(xiàn)設計的過程中，設計文檔可以視為一個活動文檔。當您對實施計劃進行調(diào)整時，也要更新文檔，這樣您就不需要一遍又一遍地向所有風險承擔者解釋這些變化。

那么，我們?nèi)绾卧u價一個設計文檔的成功呢？

我的同事Kent Rakip對這個問題的回答是:如果你能獲得正確的投資回報率(ROI)，那么這個設計文檔就是成功的。也就是說，一份成功的設計文件可能會導致:

你花了5天時間編寫設計文檔，迫使你充分考慮技術架構的不同部分。

您從評審人員那里得到反饋，并且知道架構的某些部分具有更高的風險。

為了降低項目的風險，您決定先解決這些問題。

3天后，你發(fā)現(xiàn)這些問題要么是不可能的，要么比你原來想象的要難很多。

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

本文開頭我們說過，設計文檔的目的是為了保證工作的正確完成。在上面的例子中，因為設計文檔，你只用了8天時間就決定停止項目，而不是浪費幾個月。在我看來，這似乎也是一個非常成功的結果。