一般性网络错误 请检查网络文档_如何编写好的软件设计文档
原文鏈接
作為一名軟件工程師，我花了很多時間閱讀和編寫設計文檔。在研究了數百篇這樣的文檔之后，我發現好的文檔與項目成功之間有很強的關聯性。
在本文中，我嘗試去說明如何才能編寫好的設計文檔。
本文分為4個部分：
- 為什么要寫設計文檔
- 設計文檔中應該包含哪些內容
- 如何編寫
- 流程
為什么要寫設計文檔
設計文檔 - 也被稱作技術規范 - 描述了你計劃如何去解決一個問題。已經有很多文章解釋了編碼之前編寫設計文檔的重要性。所以我在這兒要說的是:
設計文檔是保證正確的工作得以完成的最有用的工具。
人們一般會認為設計文檔是用來告訴別人系統是怎么工作的或者作為檔案留存。設計文檔確實可以起到這些作用，但這些并不是最主要目標。設計文檔的最主要目標是推動你去思考，去收集反饋。
作為一般性原則，如果你工作的項目需要1個人月或者以上，就需要寫設計文檔。但其實對于更小型的項目，編寫設計文檔也是有益的。
我想如果您還在閱讀，那么你一定是認可設計文檔的重要性。但是不同的工程團隊，甚至同一團隊的工程師，經常以不同的方式編寫設計文檔。讓我們來談談好的設計文檔的內容，風格和流程。
設計文檔中應該包含哪些內容
設計文檔描述了針對一個問題的解決方案。既然問題是多種多樣的，那么構建設計文檔的方式也是不同的。
首先應該考慮在設計文當中包含以下幾個部分。
標題和人員
設計文檔的標題，作者（項目的參與者），文檔的審閱者（我們將在后面的『流程』部分中詳細討論），以及文檔最后更新的日期。
概述
可以被公司里任何一個工程師所理解并且根據概要內容決定是否需要閱讀文檔的其余部分。這部分最多不超過3個章節。
背景
對于問題的描述、為什么要做這個項目、評估項目需要了解哪些內容以及如何融入到技術戰略，產品戰略或者是團隊的季度目標中。
目標和非目標
目標應該包括
- 描述項目對于用戶的影響 ?— 這里的用戶可以是其他團隊或者系統
- 明確衡量目標的指標 — 如果可以通過一個儀表盤展示和跟蹤這些指標就再好不過了
明確描述哪些問題不在目標范圍內也同樣重要。確保所有人對于目標的理解是一致的。
里程碑
一些可衡量的檢核點。你的PM以及你的經理的經理通過瀏覽就可以了解項目各個部分的推進情況。如果項目超過1個月，我建議你把項目拆分成多個面向用戶的里程碑。
使用自然日以便考慮延遲、假期和會議等等。它看起來可能是下面這個樣子：
開始時間：2018年6月7日
里程碑1 - 新系統MVP可在夜間模式下運行：2018年6月28日
里程碑2 - 下線舊系統：2018年7月4日
結束日期：新系統增加功能X，Y，Z：2018年7月14日
如果其中一些里程碑的預計結束時間（ETA）發生變化，可在后面增加[更新]部分。這樣項目干系人可以很容易了解到最新的計劃。
現狀
除了描述當前的系統實現以外，您還應該通過概要的流程圖來描述用戶是如何和系統交互以及數據是怎么流轉的。用戶故事是完成此類工作的很好的方式。但別忘了你的系統會有很多類型的用戶，每種用戶都有不同的用戶用例。
建議方案
這是有些人稱之為技術架構的部分。首先提供一個大的方向，然后填充大量的細節。嘗試通過用戶故事來進行細化。這部分可以包含很多內容和圖表。想象你寫完這部分就跑到一個荒島上去度假了。團隊里其他工程師可以輕松的通過這部分來實現這個方案。
替代方案
除了上面的建議方案以外，你還考慮過其他代替方案么？相比來說各有什么優缺點？有沒有考慮過不是自己實現而是購買第三方解決方案或者是使用開源方案來解決問題？
可測試性、監控和報警
我喜歡在設計文檔中包含這部分。人們往往會跳過這些工作，認為是最后才需要考慮的。但往往由于忽略了這些，出了問題以后，人們對問題為什么發生以及如何發生的一無所知。
跨團隊的影響力
方案是否會增加值班人員和運維人員的工作負擔？
方案成本是多少？
是否會引起系統回歸的問題？
是否會引入新的安全風險？
有什么風險和副作用？
服務支持團隊如何和客戶溝通？
開放性問題
任何你有疑問，不完全確定的開放性問題，如你希望讀者權衡的有爭議的結論，后續完善的工作等等。也就是我們常說的『已知的未知』（Known Unknowns）
詳細的范圍和時間表
本節主要是為參與該項目的工程師以及他們的技術主管和經理準備的。所以這段放在文檔的最后。
本質上來講，這是你計劃執行項目每一部分的分解。有很多內容是關于如何準確的界定范圍，你可以閱讀這篇文章了解更多關于范圍界定的內容。
我傾向于用文檔的這個章節來跟蹤項目任務。每當范圍的估算發生變化的時候，我就會更新這個章節。這個更多的是我個人的偏好。
如何編寫
既然談到了好的設計文檔的內容，那我們就聊聊寫作風格。我保證這個和你高中的英語課可不一樣。
盡可能簡單
不要寫的像你讀到的學術論文那樣。那樣寫是為了取悅期刊的審核員。您的文檔是為了描述您的解決方案并從其他團隊成員那里獲得反饋而編寫的。你應該使用
- 簡單的單詞
- 簡短的句子
- 各種列表
- 具體的例子，如『用戶李磊鏈接到自己的銀行賬戶，然后...』
盡可能使用圖和圖表
圖比文字更容易閱讀，圖表往往用來比較幾個可能的選項。我用Google Drawing來制作圖表。
提示：在截圖下面增加一個可編輯版本的圖表的鏈接，這樣在發生變化時可以很容易的更新它。
包含數字
問題的規模往往會決定最終的方案。為了幫助評審人員了解整個問題的概況，列舉出具體的數字，如數據庫的行數，用戶錯誤的數量以及這些數字如何隨著使用情況擴展。還記得Big-O符號么？
試著有趣一些
設計文檔不是學術論文。人們喜歡閱讀有趣的東西，所以這是讓讀者更投入的一個好辦法。但不要為了顯得有趣而偏離了文檔的主題。如果你和我一樣，不是一個很有趣的人，Joel Spolsky給過這樣的建議 — 最簡單的顯得有趣的方法是在進行一般性描述的地方，使用非常具體的例子。與其說『特殊利益群體』，不如說『左撇子的牛油果民』
做一輪自評
在把文檔發給其他人評審之前，自己先評審一遍。你對這樣的設計有什么問題和疑惑？如果有，就盡量先解決。
做一輪休假測試
加入你要休一個長假，并且沒有網絡，有沒有團隊的其他人根據這個文檔可以按你的想法實現出來？正如前面說的，設計文檔的主要目標不是分享知識，而是一種有效的方式來激發別人給你有用的反饋。
流程
又是討厭的流程！設計文檔可以幫你在浪費大量時間去實現一個錯誤的方案或者嘗試去解決一個錯誤的問題之前獲得反饋。獲得好的反饋可以有很多方法，后面會寫文章介紹。現在，讓我們討論下如何編寫設計文檔并獲得反饋。
首先，參與項目的所有人都應該參與設計的過程。雖然技術主管會做出很多決定，但每個人都應該參加討論并認同最終的決策。所以這篇文章里提到的"你"或者"你們"都是指參與項目的所有人。
其次，設計的過程不是說盯著白板天馬行空的去暢想。往往需要你著手去做一些可能的原型方案。這不意味著你要在編寫設計文檔之前就去寫生產級別的代碼。不要那樣做。但你必須要寫一些代碼去驗證你的想法。為了確保你只是寫一些實驗性質的代碼，制定一個如『原型代碼永遠不能被合并到主代碼分支』這樣的規則。
在您開始了解如何進行項目之后，你需要執行以下幾個操作
這些工作甚至可以在你編寫設計文檔之前就做，在投入更多時間以及糾結于某個具體細節前，盡早的獲得反饋。通常即便實現方法是一樣的，你的評審人也可以指出你沒想到的邊界情況，澄清一些容易混淆的問題，以及指出你未來可能遇到的一些困難。
在你完成設計文檔初稿之后，讓最初的評審人再審閱一遍。在文檔的標題和人員部分寫上評審人的名字。這也是對評審人員的一種認可和激勵。
提醒一下，對于某些設計文檔考慮邀請特定的專業評審人，如SRE工程師和安全工程師
你和評審人的工作結束之后，就可以把設計文檔發送給你的團隊以獲得更多的反饋以及知識共享。我建議收集反饋的時間限定在1周以避免拖延。承諾在問題和評論提出的當周給予回復。如果不能及時給予反饋會造成很糟糕的后果。
最后，如果你，評審人和其他的工程師對于文檔存在很多爭議，我強烈建議把所有的爭論點放在文檔的"討論"部分。然后召開會議和各方討論這些分歧。
如果某個討論的主題有超過5條評論，那么改成面對面的討論會更有效率。記住即使最終無法達成共識，你仍有責任做出最后的決定。
最近在和Shrey Banga談到這個時，我了解到Quip有類似的流程，除了找一個有經驗的工程師或者技術主管作為評審人外，他們還建議邀請一個其他團隊的工程師審閱這個文檔。我雖然沒有嘗試過，但從不同角度收集反饋明顯是有益的，同時也能改進文檔的可讀性。
完成上面所有這一切以后，就可以擼起袖子干活了。額外一點，要記得保持文檔的更新。無論是工作范圍或者方案的修改，都同步更新這個文檔。這樣你就不用一遍遍去跟別人解釋這些問題。
最后讓我們了解下如何評估一份文檔是否成功？
我的同事Kent Rakip 對此有一個很好的答案：如果該項工作的投入產出比（ROI）是合適的，那么設計文檔就是成功的。這意味著成功的設計文檔實際上會導致這樣的結果：
在文章的開頭，我們說過設計文檔的目標是確保做正確的事情。在上面的例子中，由于有了設計文檔，你只花了8天時間，而不是浪費幾個月時間才去中止這個項目。這對我來說是非常好的一個結果。
總結
以上是生活随笔為你收集整理的一般性网络错误 请检查网络文档_如何编写好的软件设计文档的全部內容，希望文章能夠幫你解決所遇到的問題。
- 上一篇： ironpython是什么2.7_是否可
- 下一篇： stream distinct去重_再来