嵌入式開發(fā)不用寫文檔？

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

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

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

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

如果你只會寫代碼，而從不寫文檔，你可能只適合中午寫代碼，因為早晚會“出事”。

不寫文檔有什么后果？

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

領導：這個功能不好、再添加一個功能、把這個功能去掉等。

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

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

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

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

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

嵌入式項目，需要哪些設計文檔？

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

當然，這里面是包含不同崗位（軟件、硬件、機械、測試等）、不同模塊等細分的各種文檔。

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

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

當然，對于我們普通的項目，需要的設計文檔可能幾個 ~ 十幾個就可以了，

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

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

舉例：xxx項目電源管理方案

下面分享一個簡單方案設計文檔。

1.封面總體

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

項目名稱、文檔版本、日期、作者、密級等。

比如：

2.文檔目錄

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

目錄很簡單，比如：

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

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

3.引言

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

4.框架

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

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

比如：

5.硬件設計

羅列硬件相關的設計信息，比如硬件供電、狀態(tài)等。

6.軟件流程

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

如果你軟件流程都不清楚，在開發(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é)議、接口設計等其他

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

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

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

審核編輯 ：李倩