原文鏈接

作為一名軟件工程師，我花了很多時(shí)間閱讀和編寫(xiě)設(shè)計(jì)文檔。在研究了數(shù)百篇這樣的文檔之后，我發(fā)現(xiàn)好的文檔與項(xiàng)目成功之間有很強(qiáng)的關(guān)聯(lián)性。

在本文中，我嘗試去說(shuō)明如何才能編寫(xiě)好的設(shè)計(jì)文檔。

本文分為4個(gè)部分：

• 為什么要寫(xiě)設(shè)計(jì)文檔
• 設(shè)計(jì)文檔中應(yīng)該包含哪些內(nèi)容
• 如何編寫(xiě)
• 流程

為什么要寫(xiě)設(shè)計(jì)文檔

設(shè)計(jì)文檔 - 也被稱(chēng)作技術(shù)規(guī)范 - 描述了你計(jì)劃如何去解決一個(gè)問(wèn)題。已經(jīng)有很多文章解釋了編碼之前編寫(xiě)設(shè)計(jì)文檔的重要性。所以我在這兒要說(shuō)的是:

設(shè)計(jì)文檔是保證正確的工作得以完成的最有用的工具。

人們一般會(huì)認(rèn)為設(shè)計(jì)文檔是用來(lái)告訴別人系統(tǒng)是怎么工作的或者作為檔案留存。設(shè)計(jì)文檔確實(shí)可以起到這些作用，但這些并不是最主要目標(biāo)。設(shè)計(jì)文檔的最主要目標(biāo)是推動(dòng)你去思考，去收集反饋。

作為一般性原則，如果你工作的項(xiàng)目需要1個(gè)人月或者以上，就需要寫(xiě)設(shè)計(jì)文檔。但其實(shí)對(duì)于更小型的項(xiàng)目，編寫(xiě)設(shè)計(jì)文檔也是有益的。

我想如果您還在閱讀，那么你一定是認(rèn)可設(shè)計(jì)文檔的重要性。但是不同的工程團(tuán)隊(duì)，甚至同一團(tuán)隊(duì)的工程師，經(jīng)常以不同的方式編寫(xiě)設(shè)計(jì)文檔。讓我們來(lái)談?wù)労玫脑O(shè)計(jì)文檔的內(nèi)容，風(fēng)格和流程。

設(shè)計(jì)文檔中應(yīng)該包含哪些內(nèi)容

設(shè)計(jì)文檔描述了針對(duì)一個(gè)問(wèn)題的解決方案。既然問(wèn)題是多種多樣的，那么構(gòu)建設(shè)計(jì)文檔的方式也是不同的。

首先應(yīng)該考慮在設(shè)計(jì)文當(dāng)中包含以下幾個(gè)部分。

標(biāo)題和人員

設(shè)計(jì)文檔的標(biāo)題，作者（項(xiàng)目的參與者），文檔的審閱者（我們將在后面的『流程』部分中詳細(xì)討論），以及文檔最后更新的日期。

概述

可以被公司里任何一個(gè)工程師所理解并且根據(jù)概要內(nèi)容決定是否需要閱讀文檔的其余部分。這部分最多不超過(guò)3個(gè)章節(jié)。

背景

對(duì)于問(wèn)題的描述、為什么要做這個(gè)項(xiàng)目、評(píng)估項(xiàng)目需要了解哪些內(nèi)容以及如何融入到技術(shù)戰(zhàn)略，產(chǎn)品戰(zhàn)略或者是團(tuán)隊(duì)的季度目標(biāo)中。

目標(biāo)和非目標(biāo)

目標(biāo)應(yīng)該包括

• 描述項(xiàng)目對(duì)于用戶(hù)的影響 ?— 這里的用戶(hù)可以是其他團(tuán)隊(duì)或者系統(tǒng)
• 明確衡量目標(biāo)的指標(biāo) — 如果可以通過(guò)一個(gè)儀表盤(pán)展示和跟蹤這些指標(biāo)就再好不過(guò)了

明確描述哪些問(wèn)題不在目標(biāo)范圍內(nèi)也同樣重要。確保所有人對(duì)于目標(biāo)的理解是一致的。

里程碑

一些可衡量的檢核點(diǎn)。你的PM以及你的經(jīng)理的經(jīng)理通過(guò)瀏覽就可以了解項(xiàng)目各個(gè)部分的推進(jìn)情況。如果項(xiàng)目超過(guò)1個(gè)月，我建議你把項(xiàng)目拆分成多個(gè)面向用戶(hù)的里程碑。

使用自然日以便考慮延遲、假期和會(huì)議等等。它看起來(lái)可能是下面這個(gè)樣子：

開(kāi)始時(shí)間：2018年6月7日

里程碑1 - 新系統(tǒng)MVP可在夜間模式下運(yùn)行：2018年6月28日

里程碑2 - 下線(xiàn)舊系統(tǒng)：2018年7月4日

結(jié)束日期：新系統(tǒng)增加功能X，Y，Z：2018年7月14日

如果其中一些里程碑的預(yù)計(jì)結(jié)束時(shí)間（ETA）發(fā)生變化，可在后面增加[更新]部分。這樣項(xiàng)目干系人可以很容易了解到最新的計(jì)劃。

現(xiàn)狀

除了描述當(dāng)前的系統(tǒng)實(shí)現(xiàn)以外，您還應(yīng)該通過(guò)概要的流程圖來(lái)描述用戶(hù)是如何和系統(tǒng)交互以及數(shù)據(jù)是怎么流轉(zhuǎn)的。用戶(hù)故事是完成此類(lèi)工作的很好的方式。但別忘了你的系統(tǒng)會(huì)有很多類(lèi)型的用戶(hù)，每種用戶(hù)都有不同的用戶(hù)用例。

建議方案

這是有些人稱(chēng)之為技術(shù)架構(gòu)的部分。首先提供一個(gè)大的方向，然后填充大量的細(xì)節(jié)。嘗試通過(guò)用戶(hù)故事來(lái)進(jìn)行細(xì)化。這部分可以包含很多內(nèi)容和圖表。想象你寫(xiě)完這部分就跑到一個(gè)荒島上去度假了。團(tuán)隊(duì)里其他工程師可以輕松的通過(guò)這部分來(lái)實(shí)現(xiàn)這個(gè)方案。

替代方案

除了上面的建議方案以外，你還考慮過(guò)其他代替方案么？相比來(lái)說(shuō)各有什么優(yōu)缺點(diǎn)？有沒(méi)有考慮過(guò)不是自己實(shí)現(xiàn)而是購(gòu)買(mǎi)第三方解決方案或者是使用開(kāi)源方案來(lái)解決問(wèn)題？

可測(cè)試性、監(jiān)控和報(bào)警

我喜歡在設(shè)計(jì)文檔中包含這部分。人們往往會(huì)跳過(guò)這些工作，認(rèn)為是最后才需要考慮的。但往往由于忽略了這些，出了問(wèn)題以后，人們對(duì)問(wèn)題為什么發(fā)生以及如何發(fā)生的一無(wú)所知。

跨團(tuán)隊(duì)的影響力

方案是否會(huì)增加值班人員和運(yùn)維人員的工作負(fù)擔(dān)？

方案成本是多少？

是否會(huì)引起系統(tǒng)回歸的問(wèn)題？

是否會(huì)引入新的安全風(fēng)險(xiǎn)？

有什么風(fēng)險(xiǎn)和副作用？

服務(wù)支持團(tuán)隊(duì)如何和客戶(hù)溝通？

開(kāi)放性問(wèn)題

任何你有疑問(wèn)，不完全確定的開(kāi)放性問(wèn)題，如你希望讀者權(quán)衡的有爭(zhēng)議的結(jié)論，后續(xù)完善的工作等等。也就是我們常說(shuō)的『已知的未知』（Known Unknowns）

詳細(xì)的范圍和時(shí)間表

本節(jié)主要是為參與該項(xiàng)目的工程師以及他們的技術(shù)主管和經(jīng)理準(zhǔn)備的。所以這段放在文檔的最后。

本質(zhì)上來(lái)講，這是你計(jì)劃執(zhí)行項(xiàng)目每一部分的分解。有很多內(nèi)容是關(guān)于如何準(zhǔn)確的界定范圍，你可以閱讀這篇文章了解更多關(guān)于范圍界定的內(nèi)容。

我傾向于用文檔的這個(gè)章節(jié)來(lái)跟蹤項(xiàng)目任務(wù)。每當(dāng)范圍的估算發(fā)生變化的時(shí)候，我就會(huì)更新這個(gè)章節(jié)。這個(gè)更多的是我個(gè)人的偏好。

如何編寫(xiě)

既然談到了好的設(shè)計(jì)文檔的內(nèi)容，那我們就聊聊寫(xiě)作風(fēng)格。我保證這個(gè)和你高中的英語(yǔ)課可不一樣。

盡可能簡(jiǎn)單

不要寫(xiě)的像你讀到的學(xué)術(shù)論文那樣。那樣寫(xiě)是為了取悅期刊的審核員。您的文檔是為了描述您的解決方案并從其他團(tuán)隊(duì)成員那里獲得反饋而編寫(xiě)的。你應(yīng)該使用

• 簡(jiǎn)單的單詞
• 簡(jiǎn)短的句子
• 各種列表
• 具體的例子，如『用戶(hù)李磊鏈接到自己的銀行賬戶(hù)，然后...』

盡可能使用圖和圖表

圖比文字更容易閱讀，圖表往往用來(lái)比較幾個(gè)可能的選項(xiàng)。我用Google Drawing來(lái)制作圖表。

提示：在截圖下面增加一個(gè)可編輯版本的圖表的鏈接，這樣在發(fā)生變化時(shí)可以很容易的更新它。

包含數(shù)字

問(wèn)題的規(guī)模往往會(huì)決定最終的方案。為了幫助評(píng)審人員了解整個(gè)問(wèn)題的概況，列舉出具體的數(shù)字，如數(shù)據(jù)庫(kù)的行數(shù)，用戶(hù)錯(cuò)誤的數(shù)量以及這些數(shù)字如何隨著使用情況擴(kuò)展。還記得Big-O符號(hào)么？

試著有趣一些

設(shè)計(jì)文檔不是學(xué)術(shù)論文。人們喜歡閱讀有趣的東西，所以這是讓讀者更投入的一個(gè)好辦法。但不要為了顯得有趣而偏離了文檔的主題。如果你和我一樣，不是一個(gè)很有趣的人，Joel Spolsky給過(guò)這樣的建議 — 最簡(jiǎn)單的顯得有趣的方法是在進(jìn)行一般性描述的地方，使用非常具體的例子。與其說(shuō)『特殊利益群體』，不如說(shuō)『左撇子的牛油果民』

做一輪自評(píng)

在把文檔發(fā)給其他人評(píng)審之前，自己先評(píng)審一遍。你對(duì)這樣的設(shè)計(jì)有什么問(wèn)題和疑惑？如果有，就盡量先解決。

做一輪休假測(cè)試

加入你要休一個(gè)長(zhǎng)假，并且沒(méi)有網(wǎng)絡(luò)，有沒(méi)有團(tuán)隊(duì)的其他人根據(jù)這個(gè)文檔可以按你的想法實(shí)現(xiàn)出來(lái)？正如前面說(shuō)的，設(shè)計(jì)文檔的主要目標(biāo)不是分享知識(shí)，而是一種有效的方式來(lái)激發(fā)別人給你有用的反饋。

流程

又是討厭的流程！設(shè)計(jì)文檔可以幫你在浪費(fèi)大量時(shí)間去實(shí)現(xiàn)一個(gè)錯(cuò)誤的方案或者嘗試去解決一個(gè)錯(cuò)誤的問(wèn)題之前獲得反饋。獲得好的反饋可以有很多方法，后面會(huì)寫(xiě)文章介紹。現(xiàn)在，讓我們討論下如何編寫(xiě)設(shè)計(jì)文檔并獲得反饋。

首先，參與項(xiàng)目的所有人都應(yīng)該參與設(shè)計(jì)的過(guò)程。雖然技術(shù)主管會(huì)做出很多決定，但每個(gè)人都應(yīng)該參加討論并認(rèn)同最終的決策。所以這篇文章里提到的"你"或者"你們"都是指參與項(xiàng)目的所有人。

其次，設(shè)計(jì)的過(guò)程不是說(shuō)盯著白板天馬行空的去暢想。往往需要你著手去做一些可能的原型方案。這不意味著你要在編寫(xiě)設(shè)計(jì)文檔之前就去寫(xiě)生產(chǎn)級(jí)別的代碼。不要那樣做。但你必須要寫(xiě)一些代碼去驗(yàn)證你的想法。為了確保你只是寫(xiě)一些實(shí)驗(yàn)性質(zhì)的代碼，制定一個(gè)如『原型代碼永遠(yuǎn)不能被合并到主代碼分支』這樣的規(guī)則。

在您開(kāi)始了解如何進(jìn)行項(xiàng)目之后，你需要執(zhí)行以下幾個(gè)操作

請(qǐng)你團(tuán)隊(duì)中經(jīng)驗(yàn)豐富的工程師或者技術(shù)主管作為評(píng)審人。理想情況下這個(gè)人應(yīng)該對(duì)要解決的問(wèn)題域非常熟悉。可以買(mǎi)杯咖啡賄賂下:)

在會(huì)議室放個(gè)白板

把你要處理的問(wèn)題跟這位工程師描述下。（這一步很重要，千萬(wàn)不要跳過(guò)）

然后把你設(shè)想的實(shí)現(xiàn)方式解釋給這位工程師，并說(shuō)服他（們）。這是非常值得去做的一件事情。

這些工作甚至可以在你編寫(xiě)設(shè)計(jì)文檔之前就做，在投入更多時(shí)間以及糾結(jié)于某個(gè)具體細(xì)節(jié)前，盡早的獲得反饋。通常即便實(shí)現(xiàn)方法是一樣的，你的評(píng)審人也可以指出你沒(méi)想到的邊界情況，澄清一些容易混淆的問(wèn)題，以及指出你未來(lái)可能遇到的一些困難。

在你完成設(shè)計(jì)文檔初稿之后，讓最初的評(píng)審人再審閱一遍。在文檔的標(biāo)題和人員部分寫(xiě)上評(píng)審人的名字。這也是對(duì)評(píng)審人員的一種認(rèn)可和激勵(lì)。

提醒一下，對(duì)于某些設(shè)計(jì)文檔考慮邀請(qǐng)?zhí)囟ǖ膶?zhuān)業(yè)評(píng)審人，如SRE工程師和安全工程師

你和評(píng)審人的工作結(jié)束之后，就可以把設(shè)計(jì)文檔發(fā)送給你的團(tuán)隊(duì)以獲得更多的反饋以及知識(shí)共享。我建議收集反饋的時(shí)間限定在1周以避免拖延。承諾在問(wèn)題和評(píng)論提出的當(dāng)周給予回復(fù)。如果不能及時(shí)給予反饋會(huì)造成很糟糕的后果。

最后，如果你，評(píng)審人和其他的工程師對(duì)于文檔存在很多爭(zhēng)議，我強(qiáng)烈建議把所有的爭(zhēng)論點(diǎn)放在文檔的"討論"部分。然后召開(kāi)會(huì)議和各方討論這些分歧。

如果某個(gè)討論的主題有超過(guò)5條評(píng)論，那么改成面對(duì)面的討論會(huì)更有效率。記住即使最終無(wú)法達(dá)成共識(shí)，你仍有責(zé)任做出最后的決定。

最近在和Shrey Banga談到這個(gè)時(shí)，我了解到Quip有類(lèi)似的流程，除了找一個(gè)有經(jīng)驗(yàn)的工程師或者技術(shù)主管作為評(píng)審人外，他們還建議邀請(qǐng)一個(gè)其他團(tuán)隊(duì)的工程師審閱這個(gè)文檔。我雖然沒(méi)有嘗試過(guò)，但從不同角度收集反饋明顯是有益的，同時(shí)也能改進(jìn)文檔的可讀性。

完成上面所有這一切以后，就可以擼起袖子干活了。額外一點(diǎn)，要記得保持文檔的更新。無(wú)論是工作范圍或者方案的修改，都同步更新這個(gè)文檔。這樣你就不用一遍遍去跟別人解釋這些問(wèn)題。

最后讓我們了解下如何評(píng)估一份文檔是否成功？

我的同事Kent Rakip 對(duì)此有一個(gè)很好的答案：如果該項(xiàng)工作的投入產(chǎn)出比（ROI）是合適的，那么設(shè)計(jì)文檔就是成功的。這意味著成功的設(shè)計(jì)文檔實(shí)際上會(huì)導(dǎo)致這樣的結(jié)果：

您花了5天時(shí)間編寫(xiě)設(shè)計(jì)文檔，這迫使你從不同的方面考慮技術(shù)架構(gòu)

你從評(píng)審人員那里得到一些反饋，如X是建議的架構(gòu)中風(fēng)險(xiǎn)最高的部分

你決定首先實(shí)施X，降低項(xiàng)目風(fēng)險(xiǎn)

3天后你發(fā)現(xiàn)X要么是不可行的，要么比原先設(shè)想的困難的多

你決定停止這個(gè)項(xiàng)目，優(yōu)先處理其他工作

在文章的開(kāi)頭，我們說(shuō)過(guò)設(shè)計(jì)文檔的目標(biāo)是確保做正確的事情。在上面的例子中，由于有了設(shè)計(jì)文檔，你只花了8天時(shí)間，而不是浪費(fèi)幾個(gè)月時(shí)間才去中止這個(gè)項(xiàng)目。這對(duì)我來(lái)說(shuō)是非常好的一個(gè)結(jié)果。

總結(jié)

以上是生活随笔為你收集整理的一般性网络错误 请检查网络文档_如何编写好的软件设计文档的全部?jī)?nèi)容，希望文章能夠幫你解決所遇到的問(wèn)題。

如果覺(jué)得生活随笔網(wǎng)站內(nèi)容還不錯(cuò)，歡迎將生活随笔推薦給好友。