最近看到有交流群在討論：嵌入式開發(fā)到底要不要寫文檔的話題。

這個話題要展開討論的話，可能要分很多種情況，公司規(guī)模、項(xiàng)目難度、管理制度。。。

分享正文之前，給大家推薦一些嵌入式相關(guān)的職位：

俗話說，不會寫文檔的工程師不是好的工程師！

如果你只會寫代碼，而從不寫文檔，你可能只適合中午寫代碼，因?yàn)樵缤頃俺鍪隆薄?/p>

不寫文檔有什么后果？

如果不寫文檔，開發(fā)過程中就會出現(xiàn)類似下面這些情況。

領(lǐng)導(dǎo)：這個功能不好、再添加一個功能、把這個功能去掉等。

軟件：這個功能不能實(shí)現(xiàn)、代碼只能重構(gòu)、一個bug引發(fā)N個bug等。

硬件：添加功能只能重新畫板、沒有考慮要預(yù)留通信接口等。

通常，在小公司不寫設(shè)計(jì)文檔很正常，但是隱患很大。反復(fù)增刪功能、調(diào)整方案這都需要付出大量時(shí)間和精力。

只是一兩次小改動都還好，如果多次、大改動的話，就會出現(xiàn)互相甩鍋、同事不和的后果。

不要問為什么，經(jīng)歷過的人都懂

嵌入式項(xiàng)目，需要哪些設(shè)計(jì)文檔？

我之前參與開發(fā)的項(xiàng)目，從需求、設(shè)計(jì)、實(shí)現(xiàn)、測試、總結(jié)等這幾個階段下來，設(shè)計(jì)文檔多的時(shí)候有上100個文檔。

當(dāng)然，這里面是包含不同崗位（軟件、硬件、機(jī)械、測試等）、不同模塊等細(xì)分的各種文檔。

對于不同的項(xiàng)目，可能設(shè)計(jì)文檔種類和數(shù)量不同，比如你一個簡單的電子手表，可只需要一個需求文檔、一個方案設(shè)計(jì)文檔就可以了。

其實(shí)，項(xiàng)目越復(fù)雜，設(shè)計(jì)文檔越多。比如京東的倉儲物流這一套系統(tǒng)，你能想想一下有多少個設(shè)計(jì)文檔嗎？光是需求階段的文檔肯定都有上百個：需求、評估、審核等各種文檔。

當(dāng)然，對于我們普通的項(xiàng)目，需要的設(shè)計(jì)文檔可能幾個 ~ 十幾個就可以了，

比如：需求文檔、評估文檔、總方案文檔、模塊方案文檔、通信協(xié)議文檔、測試用例文檔等。

每一種文檔沒有固定的格式，只需要結(jié)合你自己實(shí)際項(xiàng)目，把重點(diǎn)描述清楚，能指導(dǎo)開發(fā)人員，方便開發(fā)和設(shè)計(jì)即可。

舉例：xxx項(xiàng)目電源管理方案

下面分享一個簡單方案設(shè)計(jì)文檔。

1.封面總體

就像一個本書的封面，把主要信息羅列出來。比如：

項(xiàng)目名稱、文檔版本、日期、作者、密級等。

比如：

2.文檔目錄

作為一個技術(shù)開發(fā)人員，如果你連word的目錄都不知道怎么生成，你應(yīng)該好好反思一下了。

目錄很簡單，比如：

這里想說下，目錄是自動生成，而不是手動編輯的目錄。

我就發(fā)現(xiàn)有人的目錄居然是手動編輯的，不知道大家是不也這么“水”？

3.引言

這里引言也可以是“概述”，把整個方案的主要內(nèi)容進(jìn)行描述，比如這里簡單列幾點(diǎn)：

4.框架

框架就是首先給人第一眼就能了解你這個項(xiàng)目有些什么東西。

比如系統(tǒng)框架、軟、硬件框架等。這里需要用到一些設(shè)計(jì)框架的工具，比如：Visio.

比如：

5.硬件設(shè)計(jì)

羅列硬件相關(guān)的設(shè)計(jì)信息，比如硬件供電、狀態(tài)等。

6.軟件流程

牽涉到軟件，在方案中必不可少的一點(diǎn)，就是軟件流程。

如果你軟件流程都不清楚，在開發(fā)過程中，肯定會反反復(fù)復(fù)修改代碼，甚至修改了數(shù)十版不能用。

軟件流程網(wǎng)上有很多例子可參看，比如按鍵檢測流程：

比如電壓、電流檢測流程：

7.系統(tǒng)狀態(tài)

每一個系統(tǒng)基本都由多個狀態(tài)（或者模式），比如工作狀態(tài)、空閑狀態(tài)、故障狀態(tài)等。

你要把系統(tǒng)可能遇到的狀態(tài)都列出來，并描述清楚。比如：

8.通信協(xié)議、接口設(shè)計(jì)等其他

比如你的項(xiàng)目中會用到通信，需要把通信協(xié)議整理出來。

或者簡單描述通信相關(guān)的內(nèi)容，比如硬件使用了UART、CAN，通信協(xié)議使用CANopen、Modbus等。然后具體協(xié)議指令單獨(dú)一個文檔。（見：協(xié)議文檔）。

最后，以上內(nèi)容僅供參考，不同項(xiàng)目的情況不同。根據(jù)項(xiàng)目情況把設(shè)計(jì)中需要考慮的重要信息整理出來，并容易理解就可以了。

審核編輯 ：李倩