作為一名軟體工程師，我花了很多時間閱讀和編寫設計文件。在完成了數百篇這些文件之後，我親眼目睹了優秀設計文件與專案最終成功之間的強烈關聯。
本文試圖描述什麼使設計文件變得更好。
本文分為4個部分：
設計文件 - 也稱為技術規範 - 描述了您計畫如何解決問題。
已經有很多文章闡述過為什麼在開工之前編寫設計文件很重要。所以我在這裡要說的是：
設計文件是確保正確完成工作的最有用工具。
設計文件的主要目標是通過強迫您思考設計並收集其他人的反饋來提高您的效率。人們通常認為設計文件的目的是教會其他人關於某個系統或稍後作為文件。雖然這些可能是一部分作用，但它們並不是最根本的目的。
作為一般經驗法則，如果您正在處理可能需要1個工程師月或更長時間的專案，那麼您應該編寫設計文件。但不要止步於此 - 許多小型專案也可以從迷你設計文件中受益。
如果您還在閱讀，您會相信設計文件的重要性。但是，不同的研發團隊，甚至同一團隊的工程師，經常以非常不同的方式編寫設計文件。讓我們來談談優秀設計文件的內容，風格和寫作流程吧。
設計文件描述了問題的解決方案。由於每個問題的性質不同，您自然希望以不同的方式構建您的設計文件。
首先，以下是您應該至少考慮在下乙個設計文件中包含的部分列表：
您的設計文件的標題，作者（應該與計畫參與此專案的人員列表相同），檢查者（我們將在「處理」部分中詳細討論），以及最後更新日期。
高度概括的，公司的每位工程師都應該理解並能夠通過閱讀概覽來決定是否有必要閱讀其餘的文件。最多3段。
對手頭問題的描述，為什麼這個專案是必要的，人們需要知道什麼來評估這個專案，以及它如何適應技術戰略，產品戰略或團隊的季度目標。
目標部分應包括：
描述專案的使用者驅動影響 - 您的使用者可能是另乙個工程團隊甚至是另乙個技術系統
指定如何使用指標衡量成功 - 如果您可以鏈結到跟蹤這些指標的儀表板，則可以獲得獎勵
非目標同樣重要，它描述了您不會修復哪些問題，因此它也和目標在同一頁面上。
乙個可衡量的檢查點列表，因此您的pm和您的經理的經理可以瀏覽它並大致了解專案的不同部分何時完成。如果專案超過1個月，我建議您將專案分解為面向使用者的主要里程碑。
使用日曆日期，以便考慮無關的延遲，假期，會議等。它應該看起來像這樣：
開始日期：2023年6月7日
里程碑1 - 以暗模式執行的新系統mvp：2023年6月28日
里程碑2 - 下掉舊系統：2023年7月4日
結束日期：將功能x，y，z新增到新系統：2023年7月14日
如果其中一些里程碑的eta發生變化，請在此處新增[更新]子部分，以便相關方可以輕鬆檢視最新的情況。
除了描述當前的實現之外，您還應該通過乙個高階示例流來說明使用者如何與此系統互動和/或資料如何通過它。
使用者故事是構建此框架的絕佳方式。請記住，您的系統可能包含具有不同用例的不同型別的使用者。
有人稱之為技術架構部分。再次，嘗試通過使用者故事來具體化這一點。可以包含許多子部分和圖表。
先提供一張大圖，然後填寫大量細節，確保即使你出去度假了，團隊中的另一位工程師也可以閱讀它並按照你的描述實施解決方案。
在提出上述解決方案時，您還考慮了什麼？替代品的優點和缺點是什麼？您是否考慮購買第三方解決方案 - 或使用開源解決方案 - 解決此問題而不是構建自己的問題？
我喜歡包括這一部分，因為人們經常事後才去考慮它們或者乾脆忽略它們，當事情出了岔子，他們一籌莫展。
是否會增加外呼和開發團隊的負擔？
它會花多少錢？
它是否會導致系統延遲？
它是否暴露了安全漏洞？
有什麼負面後果和***？
支援團隊如何與客戶溝通？
任何你不確定的公開問題，你想讓讀者權衡的有爭議的決定，建議未來的工作，等等。
本節主要是由參與該項目的工程師，他們的技術主管和他們的經理閱讀。因此，本節在文件的最後。
從本質上講，這是您計畫執行專案每個部分的方式和時間的細分。有很多內容可以準確地確定範圍，因此您可以閱讀這篇文章以了解有關範圍的更多資訊。
我傾向於將設計文件的這一部分視為正在進行的專案任務***，因此每當我的範圍估計發生變化時，我都會更新它。但這更多的是個人偏好。
下面讓我們來談談寫作風格。我保證這與你的高中英語課不同。
**通常可用於比較幾個可能的選項，圖表通常比文字更容易解讀。我已經用google drawing建立圖表了。
問題嚴重程度通常決定了解決方案。為了幫助審閱者了解實際狀況，請包括實際數字，如資料庫行數，使用者錯誤數，延遲 - 以及這些資料如何隨著使用情況而擴充套件（請記住您的big-o表示法？）。
規範不是學術**。此外，人們喜歡閱讀有趣的東西，所以這是讓讀者保持參與的好方法。儘管如此，不要喧賓奪主。
在將設計文件傳送給其他人進行審核之前，請自己作為審核人員過一遍。您對此設計有什麼疑問？然後先發制人地解決它們。
如果您現在無法訪問網際網路，那麼您團隊中的某個人是否可以閱讀該文件並按照您的意圖實施該文件？
設計文件的主要目標不是知識共享，但這是一種評估清晰度的好方法，以便其他人可以實際為您提供有用的反饋。
設計文件可幫助您在浪費大量時間實施錯誤解決方案或解決錯誤問題之前獲得反饋。獲得良好反饋有很多藝術，但這是以後的事。現在，讓我們專門討論如何編寫設計文件並獲取反饋。
首先，參與專案的每個人都應該參與設計過程。如果技術主管最終推動了很多決定，那也沒關係，但是每個人都應該參與討論並參與設計。因此，本文中的「你」是乙個真正的複數「你」，包括專案中的所有人。
其次，設計過程並不意味著你盯著白板寫些理論化的想法，隨意製作潛在的解決方案原型。這與在編寫設計文件之前開始為專案編寫生產**不同，不要那樣做。但你絕對應該隨意寫一些一次性**來驗證想法。
之後，當您開始了解如何進行專案時，請執行以下操作：
請您團隊中經驗豐富的工程師或技術負責人成為您的評審員。理想情況下，這將是乙個受到尊重和/或熟悉問題細節的人。
進入帶白板的會議室。
向這位工程師描述你正在解決的問題（這是非常重要的一步，不要跳過它！）。
然後解釋你想到的實現，並說服他們這是正確的構建。
在開始編寫設計文件之前完成所有這些操作可以讓您在投入更多時間並接受任何特定解決方案之前盡快獲得反饋。通常情況下，即使實施保持不變，您的審核員也可以指出您需要覆蓋的極端案例，指出任何潛在的混淆區域，並**您以後可能遇到的困難。
然後，在您撰寫了設計文件的粗略草稿之後，讓相同的審閱者再次閱讀它，並通過在設計文件的「標題和人物」部分中新增他們的名稱作為審閱者來標記它。這為審閱者創造了額外的激勵和責任。
在這方面，考慮為設計的特定方面新增專門的審閱者（例如sre和安全工程師）。
最後，如果您，您的審閱者和其他閱讀該文件的工程師之間存在很多爭議，我強烈建議您在文件的「討論」部分中合併所有爭議點。然後，與各方召開會議，當面談論這些分歧。
在最近與shrey banga談論此事時，我了解到quip有乙個類似的過程，除了在您的團隊中擁有經驗豐富的工程師或技術負責人作為審閱者之外，他們還建議讓不同團隊的工程師審核該文件。我沒有嘗試過這個，但我當然可以看到這有助於從不同角度的人那裡獲得反饋，並提高文件的一般可讀性。
完成上述所有操作後，即可開始實施！對於額外的布朗尼點，在實施設計時將此設計文件視為活文件。每次您更改原始解決方案或更新範圍的內容時，請更新文件。這樣你就不必向所有利益相關者反覆解釋事情，你會感謝我的。
最後，讓我們真正了解一下：我們如何評估設計文件的成功？
我的同事kent rakip對此有乙個很好的答案：如果完成正確的投資回報率，設計文件就會成功。這意味著成功的設計文件實際上可能導致這樣的結果：
您花了5天時間編寫設計文件，這迫使您通過技術架構的不同部分進行思考
您可以從審閱者那裡獲得反饋，即x是建議架構中最具風險的部分
您決定首先實施x以降低專案風險
3天後，你發現x要麼不可能，要麼比你原先想要的要困難得多
您決定停止處理此專案並優先處理其他工作
在本文開頭，我們說設計文件的目標是確保正確的工作完成。 在上面的示例中，由於這個設計文件，您可能只花了8天時間而不是浪費幾個月才能中止此專案。 對我來說似乎是乙個非常成功的結果。
【推薦】 知物由學 | 內容平台、社交**如何應對虛假新聞？
【推薦】 網易雲深度剖析kubernetes優化與實踐
程式設計師如何寫出乙份好的文件？
例如，有一段描述某軟體功能的話是這樣的 該軟體模組在系統中占有重要的地位，其實現的主要功能為 2 從本地目錄中獲取檔案進行解析，並生成新的檔案放到本地的另一目錄中。3 將目錄中生成的檔案上傳到客戶指定的ftp目錄中。4 清理本地目錄中的過期檔案 清理時間及過期期限可配置 一篇 並茂的文章才是好文章，...
程式設計師如何寫出乙份好的文件？
在實際的軟體開發工作中，除了編寫 之外，程式設計師還會花大量的時間來編寫相關的研發文件，這些文件包括 詳細設計文件 單元 整合測試文件 軟體版本開發報告 軟體安裝說明 軟體公升級指導書等。在 程式設計師既要寫好 又要寫好文件 一文中，我提到過 和 文件 就像是乙個人的左膀右臂，一定要讓兩者均衡發展，...
如何寫乙份高質量的簡歷
剛畢業，進入社會的大學生總是繞不開乙個話題 如何編寫乙份高質量的簡歷。簡歷對每乙個人來說都很重要。你可以用它來求職，也可以用它來申請名校，而這些事情都是你一生中非常重要的轉折點，因此，你沒有理由不把它寫好 當你確定簡歷的內容之後，接下來就需要考慮格式和排版的問題。好的簡歷基本上只有會占用一頁，而且格...