為什麼很多人寫不了文檔（我們為什麼要寫文檔）

2023-04-23 17:22:38

菜鳥程序猿問：昨晚就加兩行代碼，怎麼搞那麼晚？

老鳥程序猿答：思考半小時。寫代碼一分鐘，寫注釋5分鐘，測試半小時，寫文檔半小時。

今天在朋友圈發了這麼一個小段子，大家都表示非常有感觸。

這篇文章再給大家分享一下《我們為什麼要寫文檔》

文檔的作用：

Ø開發人員通過文檔化的過程查錯補遺；

Ø便於評審，在早期發現技術上的問題；

Ø後續階段開發任務可能由他人承擔，輸出文檔便於他們開展工作；

Ø維護人員開展維護工作需要；

Ø文檔是必要的交付件，是產品的一個組成部分；

「所有的過程分析都要形成文檔。我們現在有一個嚴重的問題是，大家好像不喜歡寫文檔，對於需要的實現方案，通常都是一個負責人在腦袋裡想想該怎麼實現，然後郵件或電話找幾個相關人員討論一下就算可以了，可能連個會議材料或會議紀要都沒有。

而老外可不是這樣的，他們非常非常重視文檔，他們認為一個人在腦袋裡想的東西是不清晰也不全面的，有時候心裡想的認為很正確的方案實際上可能存在致命缺陷。他們要求必須把心裡的想法形成文檔才能有效的避免這種問題。寫文檔的過程中，可以更加有效的、更進一步去整理您原來心裡的思路，很多問題在您寫過文檔的過程中您就能發現；另外，文檔寫作多使用圖表，浪費口水的文字儘量少用，和我們一起工作的系統工程師在系統架構分析中就畫了五六十張圖，就算看不懂他寫的英文，從圖中我們就能夠很清晰的指導整個產品的系統架構。」——摘自一位華為員工的瑞典出差報告

可見，文檔是一種促發思考，輔助設計，查漏補缺，團隊合作的重要工具

那麼我們如何讓文檔寫的規範而有效呢？我們不是為了寫文檔而寫文檔。而是在關鍵節點，做有效的關鍵動作，來完善設計。

「流程 模板。」是關鍵：例如，我們在各個研發的關鍵節點需要輸出哪些文檔，這些文檔需要包含哪些內容。顯得尤為關鍵。

另外，流程和模板的都是死的，但是需求和設計是活的。當現有的模板不能涵蓋新設計的時候。需要設計者根據需求，補充現有的模板和流程。例如，我在設計一款刀片伺服器的時候，X86系統的BIOS開始使用SPI接口，且增加ME部分，如何實現新系統的雙BIOS切換和升級，就針對這個功能點，專門增加專題分析文檔。而部門原先規劃的「電源專題」、「時鐘專題」、「小系統專題」……並不涵蓋相關內容。

那麼就需要我們在參考模板等前人積累的情況下，不能只是墨守成規，還需要大膽優化和補充現有文檔體系。

什麼樣的文檔是好的文檔：

一個裝修需求的描述：

不好的設計文檔實例：（平直的陳述）

房子南北走向，房子大門在東側中間位置。門廳長約3米，寬2米，門廳左面是主臥室，右面是廚房。廚房3米寬，4米長，廚房門對著門廳，廚房的頂頭還有一個北陽臺，與廚房同寬，長1米。主臥室寬3米，長5米左右，房間門對著客廳。客廳與餐廳連為一體，共7米長，4米寬，與客廳相連有一南陽臺，與客廳同寬，長1.5米。餐廳的北面是衛生間，衛生間與廚房相對，中間由1米寬，3米長的過道隔開；衛生間門對著過道，南牆與廚房的南牆在一條直線上；衛生間為長方形，南牆長3米，另一邊長2米。衛生間的北面是次臥，同寬，門朝著過道，次臥長4米。過道的北端是書房門，書房南北長4米，書房有一個一米見方的門廳，書房的西牆長4米，包括1米長的門廳長度，西牆把書房和次臥分隔開。門廳東牆北端90角折向東，長2米，把書房和廚房北陽臺分隔開。

優化後的設計實例：（只是簡單地進行了分段，閱讀起來更有層次感更清晰。同時修正了「約」、「左右」等模糊的描述。）

1.房子南北走向，房子大門在東側中間位置。

2.門廳長3米，寬2米，門廳左面是主臥室，右面是廚房。

3.廚房3米寬，4米長，廚房門對著門廳，廚房的頂頭還有一個北陽臺，與廚房同寬，長1米。

4.主臥室寬3米，長5米左右，房間門對著客廳。

5.客廳與餐廳連為一體，共7米長，4米寬，與客廳相連有一南陽臺，與客廳同寬，長1.5米。

6.餐廳的北面是衛生間，衛生間與廚房相對，中間由1米寬，3米長的過道隔開；衛生間門對著過道，南牆與廚房的南牆在一條直線上；衛生間為長方形，南牆長3米，另一邊長2米。

7.衛生間的北面是次臥，同寬，門朝著過道，次臥長4米。

8.過道的北端是書房門，書房南北長4米，書房有一個一米見方的門廳，書房的西牆長4米，包括1米長的門廳長度，西牆把書房和次臥分隔開。門廳東牆北端90角折向東，長2米，把書房和廚房北陽臺分隔開。

字如不表、表不如圖：

圖形表述方式理解更容易，上圖已將房間布局信息很清晰表達出來，缺的是尺寸信息，可以在圖中標註或附以文字說明，則能完全表達清楚。

圖形應具有「自明性」，即只看圖，大體上就可理解圖意。但不應為追求自明性而使圖形過於雜亂，必要時應佐以少量的文字說明。

總之磨刀不誤砍柴工。好的工程師，文檔寫得好是必要條件。

硬體工程師要寫哪些文檔：

除了原理圖，PCB之外，我們還需要哪些文檔。

0、項目計劃，或者項目任務分配。

WBS：工作分解結構（Work Breakdown Structure） 創建WBS：創建WBS是把項目可交付成果和項目工作分解成較小的，更易於管理的組成部分的過程。

WBS是項目管理重要的專業術語之一。WBS的基本定義 ：以可交付成果為導向對項目要素進行的分組，它歸納和定義了項目的整個工作範圍每下降一層代表對項目工作的更詳細定義

1、需求跟蹤表

在需求階段明確需求，避免需求遺漏，避免需求理解差錯，避免意淫需求。

2、總體設計

關鍵器件選型、方案框圖，關鍵接口選擇。

3、專題分析

時鐘、電源、接口等等這些常規專題之外，我們還應該針對項目的薄弱點，制定特殊的專題文檔。

比如雙Flash啟動，FPGA專題，一些你開發的電路板特有的，而且可借鑑的電路很少的，都需要做好理論分析，和試驗驗證。

4、規則驅動表單

不管是自己Layout，還是別人Layout，關鍵規則，例如電源走向、線寬、熱設計要點、時序要求、信號質量要求等等。。。。

即作為Layout設計指導，也作為設計是否滿足要求的checklist。

5、測試計劃與測試方案

相當於對電路設計要求的一個梳理。在投板之前，就梳理出要測試的一些要點，以及測試的計劃和方法。

6、軟硬體接口文檔

類似於一些軟體需要知道的硬體信息的一個梳理和澄清。I2C器件的地址、CPLD作為總線訪問的一些寄存器的地址。

7、詳細設計文檔

從電路的運行環境，電路的原理、關鍵器件、接口、可靠性、可維修性、可測試性、對外界依賴性：面板背板接口、電源的需求。分別描述電路的設計思路的要點。

硬體詳設是硬體開發過程中最重要的、最正式的文檔。

在單板硬體進入到詳細設計階段，應提交單板硬體詳細設計報告。在單板硬體詳細設計中應著重體現：單板邏輯框圖及各功能模塊詳細說明，各功能模塊實現方式、地址分配、控 制方式、接口方式、存貯器空間、中斷方式、接口管腳信號詳細定義、時序說明、性能指標、 指示燈說明、外接線定義、可編程器件圖、功能模塊說明、原理圖、詳細物料清單以及單板 測試、調試計劃。有時候一塊單板的硬體和軟體分別由兩個開發人員開發，因此這時候單板 硬體詳細設計便為軟體設計者提供了一個詳細的指導，因此單板硬體詳細設計報告至關重 要。尤其是地址分配、控制方式、接口方式、中斷方式是編制單板軟體的基礎，一定要詳細寫出。

硬體詳設在很多人看來是擺設，是應付差事，應付流程。很多華為的工程師對待硬體詳設也是這樣，當做負擔。有原理圖，PCB就好了，幹嘛還要一個word文檔？

個人理解，硬體詳設是整個電路板的靈魂。文檔寫得好，設計思路才清晰。還有很多原理圖以外的內容，需要通過硬體詳設去體現。

下面的目錄文字，摘自《百度文庫》：

1 概述

1.1 背景

1.2 單板功能描述

1.3 單板運行環境說明

1.4 重要性能指標

1.5 單板功耗

1.6 必要的預備知識(可選)

2 關鍵器件

3 單板各單元詳細說明

3.1 單板功能單元劃分和業務描述

3.2 單元詳細描述

3.2.1 單元1

3.2.2 單元2

3.3 單元間配合描述

3.3.1 總線設計

3.3.2 時鐘分配

3.3.3 單板上電、復位設計

3.3.4 各單元間的時序關係

3.3.5 單板整體可測試性設計

3.3.6 軟體加載方式說明

3.3.7 基本邏輯和大規模邏輯加載方式說明

4 硬體對外接口

4.1 板際接口

4.2 系統接口

4.3 軟體接口

4.4 大規模邏輯接口

4.5 調測接口

4.6 用戶接口

5 單板可靠性綜合設計說明

5.1 單板可靠性指標

5.2 單板故障管理設計

5.2.1 主要故障模式和改進措施

5.2.2 故障定位率計算

5.2.3 冗餘單元倒換成功率計算

5.2.4 冗餘單板倒換流程

6 單板可維護性設計說明

7 單板信號完整性設計說明

7.1 關鍵器件及相關信息

7.2 關鍵信號時序要求

7.3 信號串擾、毛刺、過衝的限制範圍和保障措施：

7.4 其他重要信號及相關處理方案

7.5 物理實現關鍵技術分析

8 單板電源設計說明

8.1 單板供電原理框圖

8.2 單板電源各功能模塊詳細設計

9 器件應用可靠性設計說明

9.1 單板器件可靠應用分析結論

9.2 器件工程可靠性需求符合度分析

9.2.1 器件質量可靠性要求

9.2.2 機械應力

9.2.3 可加工性

9.2.4 電應力

9.2.5 環境應力

9.2.6 溫度應力

9.2.7 壽命及可維護性

9.3 固有失效率較高器件改進對策

9.4 上、下電過程分析

9.4.1 上下電浪湧

9.4.2 器件的上下電要求

9.5 器件可靠應用薄弱點分析

9.6 器件離散及最壞情況分析

10 單板熱設計說明

11 EMC、ESD、防護及安規設計說明

11.1 單板電源、地的分配圖

11.2 關鍵器件和關鍵信號的EMC設計

11.3 防護設計

11.4 安規設計

11.4.1 安規器件清單

11.4.2 安規實現方案說明

12 單板工藝設計說明

12.1 PCB工藝設計

12.2 工藝路線設計

12.3 工藝互連可靠性分析

12.4 元器件工藝解決方案

12.5 單板工藝結構設計

12.6 新工藝詳細設計方案

13 單板結構設計說明

13.1 拉手條或機箱結構

13.2 指示燈、面板開關

13.3 緊固件

13.4 特殊器件結構配套設計

14 其他

15 附件

15.1 安規器件清單

15.2 FMEA分析結果

其他每個環節都類似的文檔，便於設計與記錄。總之一個思路：把問題儘早暴露，避免問題遺留到項目的後面階段。越早發現問題，改正問題，這樣解決問題的代價越小。