摘要：作為一名軟件工程師，我花了很多時間閱讀和編寫設(shè)計文檔。在完成了數(shù)百篇這些文檔之后，我親眼目睹了優(yōu)秀設(shè)計文檔與項目最終成功之間的強(qiáng)烈關(guān)聯(lián)。讓我們來談?wù)剝?yōu)秀設(shè)計文檔的內(nèi)容，風(fēng)格和寫作流程吧?，F(xiàn)在，讓我們專門討論如何編寫設(shè)計文檔并獲取反饋。

作為一名軟件工程師，我花了很多時間閱讀和編寫設(shè)計文檔。在完成了數(shù)百篇這些文檔之后，我親眼目睹了優(yōu)秀設(shè)計文檔與項目最終成功之間的強(qiáng)烈關(guān)聯(lián)。

本文試圖描述什么使設(shè)計文檔變得更好。

本文分為4個部分：

為什么要寫一份設(shè)計文檔

要包含在設(shè)計文檔中的內(nèi)容

怎么寫

相關(guān)過程

為什么要寫一個設(shè)計文檔？
設(shè)計文檔 - 也稱為技術(shù)規(guī)范 - 描述了您計劃如何解決問題。

已經(jīng)有很多文章闡述過為什么在開工之前編寫設(shè)計文檔很重要。所以我在這里要說的是：

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

設(shè)計文檔的主要目標(biāo)是通過強(qiáng)迫您思考設(shè)計并收集其他人的反饋來提高您的效率。人們通常認(rèn)為設(shè)計文檔的目的是教會其他人關(guān)于某個系統(tǒng)或稍后作為文檔。雖然這些可能是一部分作用，但它們并不是最根本的目的。

作為一般經(jīng)驗法則，如果您正在處理可能需要1個工程師月或更長時間的項目，那么您應(yīng)該編寫設(shè)計文檔。但不要止步于此 - 許多小型項目也可以從迷你設(shè)計文檔中受益。

如果您還在閱讀，您會相信設(shè)計文檔的重要性。但是，不同的研發(fā)團(tuán)隊，甚至同一團(tuán)隊的工程師，經(jīng)常以非常不同的方式編寫設(shè)計文檔。讓我們來談?wù)剝?yōu)秀設(shè)計文檔的內(nèi)容，風(fēng)格和寫作流程吧。

設(shè)計文檔中應(yīng)該包含哪些內(nèi)容？
設(shè)計文檔描述了問題的解決方案。由于每個問題的性質(zhì)不同，您自然希望以不同的方式構(gòu)建您的設(shè)計文檔。

首先，以下是您應(yīng)該至少考慮在下一個設(shè)計文檔中包含的部分列表：

標(biāo)題和參與者
您的設(shè)計文檔的標(biāo)題，作者（應(yīng)該與計劃參與此項目的人員列表相同），檢查者（我們將在“處理”部分中詳細(xì)討論），以及最后更新日期。

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

背景
對手頭問題的描述，為什么這個項目是必要的，人們需要知道什么來評估這個項目，以及它如何適應(yīng)技術(shù)戰(zhàn)略，產(chǎn)品戰(zhàn)略或團(tuán)隊的季度目標(biāo)。

目標(biāo)和非目標(biāo)
目標(biāo)部分應(yīng)包括：

描述項目的用戶驅(qū)動影響 - 您的用戶可能是另一個工程團(tuán)隊甚至是另一個技術(shù)系統(tǒng)
指定如何使用指標(biāo)衡量成功 - 如果您可以鏈接到跟蹤這些指標(biāo)的儀表板，則可以獲得獎勵
非目標(biāo)同樣重要，它描述了您不會修復(fù)哪些問題，因此它也和目標(biāo)在同一頁面上。

里程碑
一個可衡量的檢查點列表，因此您的PM和您的經(jīng)理的經(jīng)理可以瀏覽它并大致了解項目的不同部分何時完成。如果項目超過1個月，我建議您將項目分解為面向用戶的主要里程碑。

使用日歷日期，以便考慮無關(guān)的延遲，假期，會議等。它應(yīng)該看起來像這樣：

開始日期：2018年6月7日
里程碑1 - 以暗模式運行的新系統(tǒng)MVP：2018年6月28日
里程碑2 - 下掉舊系統(tǒng)：2018年7月4日
結(jié)束日期：將功能X，Y，Z添加到新系統(tǒng)：2018年7月14日

如果其中一些里程碑的ETA發(fā)生變化，請在此處添加[更新]子部分，以便相關(guān)方可以輕松查看最新的情況。

當(dāng)前解決方案
除了描述當(dāng)前的實現(xiàn)之外，您還應(yīng)該通過一個高級示例流來說明用戶如何與此系統(tǒng)交互和/或數(shù)據(jù)如何通過它。

用戶故事是構(gòu)建此框架的絕佳方式。請記住，您的系統(tǒng)可能包含具有不同用例的不同類型的用戶。

推薦解決方案
有人稱之為技術(shù)架構(gòu)部分。再次，嘗試通過用戶故事來具體化這一點?？梢园S多子部分和圖表。

先提供一張大圖，然后填寫大量細(xì)節(jié)，確保即使你出去度假了，團(tuán)隊中的另一位工程師也可以閱讀它并按照你的描述實施解決方案。

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

監(jiān)控和警報
我喜歡包括這一部分，因為人們經(jīng)常事后才去考慮它們或者干脆忽略它們，當(dāng)事情出了岔子，他們一籌莫展。

跨團(tuán)隊配合方面
是否會增加外呼和開發(fā)團(tuán)隊的負(fù)擔(dān)？
它會花多少錢？
它是否會導(dǎo)致系統(tǒng)延遲？
它是否暴露了安全漏洞？
有什么負(fù)面后果和副作用？
支持團(tuán)隊如何與客戶溝通？

討論
任何你不確定的公開問題，你想讓讀者權(quán)衡的有爭議的決定，建議未來的工作，等等。

詳細(xì)的范圍和時間表
本節(jié)主要是由參與該項目的工程師，他們的技術(shù)主管和他們的經(jīng)理閱讀。因此，本節(jié)在文檔的最后。

從本質(zhì)上講，這是您計劃執(zhí)行項目每個部分的方式和時間的細(xì)分。有很多內(nèi)容可以準(zhǔn)確地確定范圍，因此您可以閱讀這篇文章以了解有關(guān)范圍的更多信息。

我傾向于將設(shè)計文檔的這一部分視為正在進(jìn)行的項目任務(wù)跟蹤器，因此每當(dāng)我的范圍估計發(fā)生變化時，我都會更新它。但這更多的是個人偏好。

怎么寫
下面讓我們來談?wù)剬懽黠L(fēng)格。我保證這與你的高中英語課不同。

寫得盡可能簡單
不要試著寫你讀過的學(xué)術(shù)論文。它們是為了給期刊評論家留下深刻印象。您的文檔是為了描述您的解決方案并從您的隊友那里獲得反饋而編寫的。多運用類似這些：

簡單的話

短句

項目符號列表和/或編號列表

具體的例子，如“用戶愛麗絲連接她的銀行賬戶，然后…”

添加大量表格和圖示
表格通?？捎糜诒容^幾個可能的選項，圖表通常比文本更容易解讀。我已經(jīng)用Google Drawing創(chuàng)建圖表了。

專業(yè)提示：請記住在屏幕截圖下添加指向圖表的可編輯版本的鏈接，以便以后在事情不可避免地發(fā)生變化時輕松更新。

包括數(shù)字
問題嚴(yán)重程度通常決定了解決方案。為了幫助審閱者了解實際狀況，請包括實際數(shù)字，如數(shù)據(jù)庫行數(shù)，用戶錯誤數(shù)，延遲 - 以及這些數(shù)據(jù)如何隨著使用情況而擴(kuò)展（請記住您的Big-O表示法？）。

試著變得有趣
規(guī)范不是學(xué)術(shù)論文。此外，人們喜歡閱讀有趣的東西，所以這是讓讀者保持參與的好方法。盡管如此，不要喧賓奪主。

進(jìn)行測試
在將設(shè)計文檔發(fā)送給其他人進(jìn)行審核之前，請自己作為審核人員過一遍。您對此設(shè)計有什么疑問？然后先發(fā)制人地解決它們。

做假期測試
如果您現(xiàn)在無法訪問互聯(lián)網(wǎng)，那么您團(tuán)隊中的某個人是否可以閱讀該文檔并按照您的意圖實施該文檔？

設(shè)計文檔的主要目標(biāo)不是知識共享，但這是一種評估清晰度的好方法，以便其他人可以實際為您提供有用的反饋。

處理
設(shè)計文檔可幫助您在浪費大量時間實施錯誤解決方案或解決錯誤問題之前獲得反饋。獲得良好反饋有很多藝術(shù)，但這是以后的事。現(xiàn)在，讓我們專門討論如何編寫設(shè)計文檔并獲取反饋。

首先，參與項目的每個人都應(yīng)該參與設(shè)計過程。如果技術(shù)主管最終推動了很多決定，那也沒關(guān)系，但是每個人都應(yīng)該參與討論并參與設(shè)計。因此，本文中的“你”是一個真正的復(fù)數(shù)“你”，包括項目中的所有人。

其次，設(shè)計過程并不意味著你盯著白板寫些理論化的想法，隨意制作潛在的解決方案原型。這與在編寫設(shè)計文檔之前開始為項目編寫生產(chǎn)代碼不同，不要那樣做。但你絕對應(yīng)該隨意寫一些一次性代碼來驗證想法。

之后，當(dāng)您開始了解如何進(jìn)行項目時，請執(zhí)行以下操作：

請您團(tuán)隊中經(jīng)驗豐富的工程師或技術(shù)負(fù)責(zé)人成為您的評審員。理想情況下，這將是一個受到尊重和/或熟悉問題細(xì)節(jié)的人。

進(jìn)入帶白板的會議室。

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

然后解釋你想到的實現(xiàn)，并說服他們這是正確的構(gòu)建。

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

然后，在您撰寫了設(shè)計文檔的粗略草稿之后，讓相同的審閱者再次閱讀它，并通過在設(shè)計文檔的“標(biāo)題和人物”部分中添加他們的名稱作為審閱者來標(biāo)記它。這為審閱者創(chuàng)造了額外的激勵和責(zé)任。

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

一旦您和審核人員確定了，請隨時將設(shè)計文檔發(fā)送給您的團(tuán)隊，以獲得額外的反饋和知識共享。我建議將反饋收集過程的時間限制在1周左右，以避免延誤。致力于解決人們在該周內(nèi)留下的所有問題和評論。

最后，如果您，您的審閱者和其他閱讀該文檔的工程師之間存在很多爭議，我強(qiáng)烈建議您在文檔的“討論”部分中合并所有爭議點。然后，與各方召開會議，當(dāng)面談?wù)撨@些分歧。

每當(dāng)討論主題長度超過5條評論時，轉(zhuǎn)向當(dāng)面討論往往效率更高。請記住，即使每個人都無法達(dá)成共識，您仍然有責(zé)任進(jìn)行最后的溝通。

在最近與Shrey Banga談?wù)摯耸聲r，我了解到Quip有一個類似的過程，除了在您的團(tuán)隊中擁有經(jīng)驗豐富的工程師或技術(shù)負(fù)責(zé)人作為審閱者之外，他們還建議讓不同團(tuán)隊的工程師審核該文檔。我沒有嘗試過這個，但我當(dāng)然可以看到這有助于從不同角度的人那里獲得反饋，并提高文檔的一般可讀性。

完成上述所有操作后，即可開始實施！對于額外的布朗尼點，在實施設(shè)計時將此設(shè)計文檔視為活文檔。每次您更改原始解決方案或更新范圍的內(nèi)容時，請更新文檔。這樣你就不必向所有利益相關(guān)者反復(fù)解釋事情，你會感謝我的。

最后，讓我們真正了解一下：我們?nèi)绾卧u估設(shè)計文檔的成功？

我的同事Kent Rakip對此有一個很好的答案：如果完成正確的投資回報率，設(shè)計文檔就會成功。這意味著成功的設(shè)計文檔實際上可能導(dǎo)致這樣的結(jié)果：

您花了5天時間編寫設(shè)計文檔，這迫使您通過技術(shù)架構(gòu)的不同部分進(jìn)行思考

您可以從審閱者那里獲得反饋，即X是建議架構(gòu)中最具風(fēng)險的部分

您決定首先實施X以降低項目風(fēng)險

3天后，你發(fā)現(xiàn)X要么不可能，要么比你原先想要的要困難得多

您決定停止處理此項目并優(yōu)先處理其他工作

在本文開頭，我們說設(shè)計文檔的目標(biāo)是確保正確的工作完成。 在上面的示例中，由于這個設(shè)計文檔，您可能只花了8天時間而不是浪費幾個月才能中止此項目。 對我來說似乎是一個非常成功的結(jié)果。

如果您喜歡這篇文章，請在Twitter上關(guān)注我，了解有關(guān)工程，流程和后端系統(tǒng)的更多帖子。

原文地址

文章來源： 網(wǎng)易云社區(qū)