谷歌軟件工程文化的主要元素之一就是通過設(shè)計文檔定義軟件設(shè)計。在開始項目編碼工作之前，軟件系統(tǒng)或應(yīng)用程序的作者會創(chuàng)建這些相對非正式的文檔。設(shè)計文檔記錄了高級實現(xiàn)策略和關(guān)鍵設(shè)計決策，并且重點記錄了這些決策之間的權(quán)衡考慮。
作為軟件工程師，我們的工作本質(zhì)上不是生產(chǎn)代碼，而是解決問題。非結(jié)構(gòu)化文本，類似設(shè)計文檔的形式，也許是在項目早期解決問題比較好的工具，因為它易于理解、更簡潔，且以比代碼更高的層次來溝通問題和方案。
除軟件設(shè)計的原始文檔外，設(shè)計文檔還實現(xiàn)了軟件開發(fā)周期中的如下功能：
在早期發(fā)現(xiàn)設(shè)計問題，而那時變更的成本還比較小
在組織內(nèi)圍繞設(shè)計達(dá)成共識
確?？紤]到交叉領(lǐng)域的問題
將高級工程師的知識擴展到組織中
圍繞設(shè)計決策形成組織記憶的基礎(chǔ)
在軟件設(shè)計師的技術(shù)組合中充當(dāng)總結(jié)工具
設(shè)計文檔是非正式文檔，因此它們的內(nèi)容不會遵循嚴(yán)格的準(zhǔn)則。一個首要原則是，針對具體項目可以用任何最合理的形式編寫。
話雖如此，形成的特定結(jié)構(gòu)必定有其價值所在。
這一部分會粗略地向讀者介紹新系統(tǒng)是如何構(gòu)建的以及實際情況如何。這不是需求文檔。請保持簡潔！我們的目標(biāo)是直接讓讀者了解最新情況，但先前的一些情況可以被推測或者能鏈接到詳細(xì)信息。這個部分應(yīng)該完全聚焦于客觀背景事實。
這一部分會列舉出系統(tǒng)目標(biāo)是什么，但有時候更重要的是，列出系統(tǒng)的 non-goals。注意，non-goals 并不是像“系統(tǒng)不應(yīng)該崩潰”這樣的負(fù)面目標(biāo)，而是那些本可以合理地成為目標(biāo)但卻明確地選擇不作為目標(biāo)的東西。一個很好的例子是“ACID 準(zhǔn)則”；當(dāng)設(shè)計數(shù)據(jù)庫時，你肯定想知道這是一個目標(biāo)還是一個非目標(biāo)。而如果這是一個 non-goals，如果它不會阻礙目標(biāo)的實現(xiàn)，那你仍然可以選擇一個提供它的解決方案。
這一部分應(yīng)該從概述開始，然后擴展至詳情。
設(shè)計文檔適合寫你在設(shè)計軟件時所做的權(quán)衡。把重點放在這些權(quán)衡上，來產(chǎn)出具有長期價值的文檔。換句話說，給定上下文（事實）、目標(biāo)和 non-goals（需求），設(shè)計文檔可以提供建議方案并展示為什么某個特定方案最能滿足那些目標(biāo)。
在比較正式的媒介上，編寫文檔的目的是提供靈活性，以適當(dāng)?shù)姆绞秸故臼诸^的問題。因此，對于如何真正地描述設(shè)計并沒有明確的指南。
盡管如此，對于大部分設(shè)計文檔來說，一些最佳實踐和重復(fù)話題都很有意義：
在許多文檔中， 系統(tǒng)語境圖都非常有用。這樣一張圖將系統(tǒng)作為更大技術(shù)環(huán)境的一部分展示，允許讀者結(jié)合他們已經(jīng)熟悉的環(huán)境進(jìn)行理解。
https://en.wikipedia.org/wiki/System_context_diagram
系統(tǒng)語境圖示例
如果正在設(shè)計的系統(tǒng)暴露一個 API，那么勾勒出這個 API 通常是個好主意。然而，在大多數(shù)情況下，人們應(yīng)該按捺住將正式接口或數(shù)據(jù)定義復(fù)制粘貼到文檔中的誘惑，因為這些定義通常都很冗長，包含一些不必要的細(xì)節(jié)，而且很快就會過時。相反，人們應(yīng)該聚焦于與設(shè)計及其權(quán)衡相關(guān)的部分。
存儲數(shù)據(jù)的系統(tǒng)應(yīng)該討論如何及用何種大致的形式存儲數(shù)據(jù)。和關(guān)于 API 的建議類似，并且理由相同，應(yīng)該避免復(fù)制粘貼完整的模式定義。相反，要聚焦于與設(shè)計及其權(quán)衡相關(guān)的部分。
除了一些描述新奇算法的場景，設(shè)計文檔應(yīng)該很少包含代碼或偽代碼。在適當(dāng)?shù)那闆r下，可以鏈接到設(shè)計實現(xiàn)的原型。
影響軟件設(shè)計和設(shè)計文檔形狀的主要因素之一就是方案空間的約束度。
極端的一個例子就是“綠地軟件項目”，我們都知道目標(biāo)，而且解決方案可以是任何最有意義的方案。這樣一個文檔可能涉及面很廣，但它還需要快速定義一組規(guī)則，來允許對一組可控的解決方案進(jìn)行細(xì)致研究。
另一方面，系統(tǒng)中可能的方案都定義得很好，但是完全不清楚如何將它們組合起來實現(xiàn)目標(biāo)。這可能是一個很難更改的遺留系統(tǒng)，而且它不是按照你希望的樣子設(shè)計的，或者是一個程序庫設(shè)計，需要在宿主編程語言的約束下運行。
在這種情況下，你也許能列舉出相對容易做的事情，但你需要費些心思將這些事情組合起來，從而實現(xiàn)目標(biāo)。可能有很多方案，但沒有一個是非常好的，因此，這樣一個文檔應(yīng)該聚焦于根據(jù)所有確定的權(quán)衡點來選擇最佳方案。
本節(jié)列出了能合理實現(xiàn)類似結(jié)果的備選設(shè)計。重點應(yīng)該放在每個設(shè)計所做的權(quán)衡，以及這些權(quán)衡如何導(dǎo)致選擇這個設(shè)計的決定，而這正是這個文檔的首要主題。
雖然簡略介紹最終沒有被選中的方案也沒有什么，但是本節(jié)會非常明確地展示為什么被選中的方案是針對項目目標(biāo)的最佳方案，以及讀者可能想知道的，為什么其它方案提供的權(quán)衡針對目標(biāo)方案是不太理想的。
在這里，你的組織可以確保像安全性、隱私性、可觀測性等跨領(lǐng)域問題被納入考慮范圍。這些通常都是相對短的部分，解釋了設(shè)計如何影響這些關(guān)注點以及如何解決這些關(guān)注點。團(tuán)隊?wèi)?yīng)該將這些關(guān)注點標(biāo)準(zhǔn)化。
由于它們的重要性，谷歌項目需要有一個專門的隱私設(shè)計文檔，并且有專門的隱私和安全審查。雖然這些審查只需要在項目啟動時完成，但最好盡早與隱私和安全團(tuán)隊接觸，以確保設(shè)計從一開始就將這些考慮在內(nèi)。對于這些主題的專用文檔，中心設(shè)計文檔當(dāng)然可以只引用它們，而不是詳細(xì)介紹。
設(shè)計文檔需要足夠豐富凝練，以便忙碌的人可以真正閱讀。一個比較大的項目最佳長度是 10-20 頁。如果你的文檔太長，最好將問題分解成多個可控的子問題。值得一提的是，寫一份 1-3 頁的“迷你設(shè)計文檔”是絕對可行的。這對于敏捷項目中的增量改進(jìn)或子任務(wù)特別有幫助——你仍然可以像處理一個長文檔那樣處理所有步驟，只需要保持簡潔并且聚焦于一個有限的問題集。
寫設(shè)計文檔是有開銷的。是否編寫設(shè)計文檔的決定歸根結(jié)底于核心權(quán)衡，即圍繞設(shè)計、文檔、高級評審等方面達(dá)成共識的好處是否超過創(chuàng)建文檔的額外工作負(fù)擔(dān)。這個決策的核心在于設(shè)計問題的核心是否模棱兩可——這取決于問題的復(fù)雜度或者方案的復(fù)雜度，或者兼而有之。如果設(shè)計問題的核心并不模糊，那么就幾乎沒有價值去編寫一份文檔。
如果設(shè)計文檔實際上是實現(xiàn)手冊，那么這就是一個設(shè)計文檔不必要的明確指標(biāo)。如果一個文檔基本上在說“我們是如何實現(xiàn)的”，而不涉及權(quán)衡、替代方案和決策解釋（或者這個方案是如此明顯以至于不需要權(quán)衡），那么直接編寫實際程序可能是個更好的主意。
最后，創(chuàng)建和審核一個設(shè)計文檔的開銷可能與創(chuàng)建原型和快速迭代不兼容。然而，大部分軟件項目確實存在一些實際已知的問題。遵循敏捷開發(fā)方法并不是不花時間去解決實際已知問題的借口。另外，原型構(gòu)建本身可能就是創(chuàng)建設(shè)計文檔的一部分?！拔以囘^了，它起作用”是選擇一個設(shè)計的最佳論據(jù)之一。
設(shè)計文檔的生命周期的幾個步驟是：
創(chuàng)建并快速迭代
審核（可能有多輪）
實現(xiàn)和迭代
維護(hù)和學(xué)習(xí)
在這個階段，你編寫文檔。有時會和一組作者合作編寫。
當(dāng)文檔被分享給最了解問題領(lǐng)域的同事（通常屬于同一個團(tuán)隊）時，這個階段會快速演變到快速迭代期，通過他們將問題搞清楚以及提供建議，讓文檔進(jìn)入第一個相對穩(wěn)定的版本。
雖然你肯定會發(fā)現(xiàn)工程師甚至團(tuán)隊喜歡版本控制和代碼評審工具來創(chuàng)建文檔，但是谷歌的大部分設(shè)計文檔是用 Google Docs 創(chuàng)建的，并且大量使用了它的協(xié)作功能。
在評審階段，設(shè)計文檔會被分享到除初始作者和密切協(xié)作者之外的更廣泛讀者。評審可以帶來許多價值，但它們也是危險的開銷陷阱，所以要明智地處理評審。
評審有多種形式：比較輕量的方式是將文檔發(fā)送給（比較廣泛的）團(tuán)隊列表中，讓人們都有機會看一看。討論主要發(fā)生在文檔的評論環(huán)節(jié)。比較重的評審，是正式的設(shè)計評審會議，在會議上，作者將文檔（通常是一個專門的演示文稿）展示給級別較高的工程師。谷歌的許多團(tuán)隊都會為此定期召開會議，工程師可以報名參與評審。當(dāng)然，等待這些會議的召開會明顯減慢開發(fā)進(jìn)度。工程師可以通過直接尋求關(guān)鍵性反饋來緩解這種情況，而不是阻礙更廣泛的評審流程。
當(dāng)谷歌是一個比較小的公司時，人們習(xí)慣于將設(shè)計發(fā)送到一個核心郵件列表，高級工程師在他們閑暇時評審這些設(shè)計。這可能是一個很好的方式來處理你公司的事情。其中一個好處是，這確實在公司中建立了一種相對非正式的軟件設(shè)計文化。但是，當(dāng)公司規(guī)模擴大到一個相對大的工程團(tuán)隊時，維持集中化的方式變得不再可行。
評審帶來的主要價值是，它們提供了一個機會將組織的綜合經(jīng)驗融入到設(shè)計中。最為一貫的是，評審階段可以確保將跨領(lǐng)域的關(guān)注點，例如觀測性、安全性和隱私性考慮在內(nèi)。評審的主要價值不在于發(fā)現(xiàn)問題本身，而是在開發(fā)周期的早期就發(fā)現(xiàn)問題，此時進(jìn)行更改的成本仍然相對較小。
當(dāng)事情進(jìn)展到確信進(jìn)一步評審不再需要對設(shè)計進(jìn)行重大改動時，就可以開始實現(xiàn)了。當(dāng)計劃與現(xiàn)實沖突時，不可避免地會出現(xiàn)一些缺點、解決不了的需求、深思熟慮的猜測結(jié)果是錯誤的等情況，并且需要變更設(shè)計。這種情況下，強烈建議更新設(shè)計文檔。
一般來說：如果設(shè)計的系統(tǒng)還沒有交付，一定要更新文檔。在實踐中，我們?nèi)祟惗疾簧瞄L更新文檔，而且由于其它實際原因，更改通常被獨自放到新文檔中。這導(dǎo)致最終狀態(tài)有點類似美國憲法附帶一堆修正案，而不是一份一致的文件。從原始文檔到這些修正文件的鏈接，對于將來嘗試通過設(shè)計文檔來理解目標(biāo)系統(tǒng)的可憐的維護(hù)程序員是非常有用的。
當(dāng)谷歌工程師面對一個他們從未接觸過的系統(tǒng)時，他們的第一個問題通常是“設(shè)計文檔在哪里？”。雖然設(shè)計文檔和其它文檔一樣，會隨著時間的推移與現(xiàn)實脫節(jié)，但它們?nèi)匀怀３Ｊ橇私庀到y(tǒng)創(chuàng)建思想的最容易的入口。
作為作者，自我回顧并在 1 年或 2 年以后重新閱讀你的設(shè)計文檔。你做對了什么？你做錯了什么？今天你怎么做才會做出不同的決定？回答這些問題是一個很好的方法，來實現(xiàn)工程師進(jìn)階和隨著時間的推移提高軟件設(shè)計技能。
設(shè)計文檔是一個很好的方法，用來在解決軟件項目中最難的問題方面提高清晰度并達(dá)成共識。設(shè)計文檔節(jié)省了資金，因為它們可以通過預(yù)先調(diào)查，避免編寫無法實現(xiàn)項目目的的“兔子洞”（譯者注，rabbit holes 源自《愛麗斯漫游仙境》，指通向未知世界的入口）；設(shè)計文檔也損耗資金，因為創(chuàng)建和評審設(shè)計文檔需要時間。所以，針對你的項目要明智地選擇！
當(dāng)考慮編寫一個設(shè)計文檔時，想一想以下幾點：
你是否不確定正確的軟件設(shè)計，是否有必要花費前期時間來增加確定性？
與此相關(guān)的是，因為高級工程師可能無法審核每一次代碼變更，因此讓他們參與設(shè)計是否有幫助？
軟件設(shè)計是否模棱兩可甚至是有爭議的，而圍繞設(shè)計文檔在組織上達(dá)成共識是有價值的？
我的團(tuán)隊是否有時會忘記考慮設(shè)計中的隱私性、安全性、日志記錄或其它交叉問題？
是否強烈需要文檔來對組織中的遺留系統(tǒng)的設(shè)計提供高層次的見解？
如果您對這些問題中的 3 個及以上回答為“是”，那么設(shè)計文檔可能是開始你的下一個軟件項目的好方法。
原文鏈接：
https://www.industrialempathy.com/posts/design-docs-at-google/
