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

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

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

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

文檔的作用：

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

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

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

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

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

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

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

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

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

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

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

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

模闆

需求

SRS文檔

接口文檔

設計

概要設計

詳細設計

軟件設計

移植設計

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

一個裝修需求的描述：

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

房子南北走向，房子大門在東側中間位置。門廳長約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、詳細設計文檔

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

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

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分析結果

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