嵌入式項(xiàng)目需要寫哪些文檔？

作者 |?strongerHuang，微信公眾號(hào) | strongerHuang

寫文檔對(duì)于嵌入式工程師來(lái)說(shuō)“很難”，特別是一個(gè)項(xiàng)目有數(shù)十個(gè)文檔要寫的情況下。

那么，你們平時(shí)開(kāi)發(fā)嵌入式項(xiàng)目，會(huì)寫文檔嗎？一般要寫多少個(gè)文檔？哪些類型的文檔？

這類問(wèn)題也是讀者問(wèn)的比較多的問(wèn)題，今天就來(lái)簡(jiǎn)單講講。

嵌入式項(xiàng)目到底要不要寫文檔？

有的公司做一個(gè)嵌入式項(xiàng)目，從頭到尾沒(méi)有一個(gè)文檔，都是口頭對(duì)接。而有的公司，開(kāi)發(fā)一個(gè)嵌入式項(xiàng)目，文檔有上百份。

我曾經(jīng)開(kāi)發(fā)過(guò)0文檔的項(xiàng)目，也有五、六十份文檔的項(xiàng)目（當(dāng)然，不全是我寫的，我只寫了其中幾份）。

你會(huì)發(fā)現(xiàn)，嵌入式項(xiàng)目到底要不要寫文檔，與公司性質(zhì)、管理、項(xiàng)目大小等有關(guān)系。

一般來(lái)說(shuō)，小公司人員不足、管理也不完善，不看重文檔。反之，大公司不管項(xiàng)目大小，都有嚴(yán)格的規(guī)范，該有的文檔一份不會(huì)少，即便文檔內(nèi)容不多。

嵌入式項(xiàng)目需要寫哪些文檔？

嚴(yán)格來(lái)說(shuō)，沒(méi)有文檔的嵌入式項(xiàng)目不是好的項(xiàng)目。

為什么這么說(shuō)，相信很多讀者都接手過(guò)“爛項(xiàng)目”，比如前兩天給大家分享的《單片機(jī)項(xiàng)目中太多全局變量有什么弊端？》。其實(shí)，很多爛項(xiàng)目有一部分原因就是因?yàn)闆](méi)有文檔造成的。

那么，我們站在開(kāi)發(fā)者的角度，你考慮過(guò)有必要寫的文檔有哪些嗎？下面分享一下。

1、需求文檔

需求文檔很關(guān)鍵，所有的后續(xù)研發(fā)工作都是基于需求而來(lái)，它詳細(xì)描述了嵌入式系統(tǒng)的功能需求、性能需求、接口需求等。并且助于確保開(kāi)發(fā)團(tuán)隊(duì)對(duì)項(xiàng)目的理解保持一致，并作為后續(xù)設(shè)計(jì)和開(kāi)發(fā)工作的基礎(chǔ)。

需求文檔在于確定項(xiàng)目的具體目標(biāo)、功能需求以及性能指標(biāo)。分析項(xiàng)目的復(fù)雜性和可行性，確保所選單片機(jī)、各種器件能夠滿足需求等。

如果公司人員多、細(xì)分工作的話，需求文檔應(yīng)該有多個(gè)。

2、設(shè)計(jì)文檔

設(shè)計(jì)文檔包括結(jié)構(gòu)設(shè)計(jì)文檔、硬件設(shè)計(jì)文檔、軟件設(shè)計(jì)文檔等。

結(jié)構(gòu)設(shè)計(jì)文檔包含結(jié)構(gòu)尺寸、大小、外觀等內(nèi)容，硬件設(shè)計(jì)文檔描述包含嵌入式系統(tǒng)的硬件架構(gòu)、電路板設(shè)計(jì)、元件選擇等內(nèi)容；軟件設(shè)計(jì)文檔則涉及軟件架構(gòu)、模塊劃分、接口定義等。

這些文檔有助于團(tuán)隊(duì)成員理解系統(tǒng)的整體結(jié)構(gòu)和各個(gè)部分的功能。

3、開(kāi)發(fā)文檔

這里開(kāi)發(fā)文檔，也是實(shí)現(xiàn)文檔。這一部分文檔應(yīng)該是開(kāi)發(fā)者寫的最多的，主要是詳細(xì)描述、記錄了嵌入式系統(tǒng)的具體實(shí)現(xiàn)過(guò)程，包括源代碼、頭文件、庫(kù)文件等。

這些文檔對(duì)于后續(xù)的代碼維護(hù)和升級(jí)至關(guān)重要，也有助于團(tuán)隊(duì)成員之間的代碼共享和協(xié)作。

你會(huì)發(fā)現(xiàn)，有時(shí)候軟件和硬件存在互相甩鍋的情況。

4、測(cè)試文檔

測(cè)試文檔包括測(cè)試計(jì)劃、測(cè)試用例、測(cè)試報(bào)告等。

詳細(xì)描述了測(cè)試的過(guò)程、結(jié)果和問(wèn)題分析，有助于確保嵌入式系統(tǒng)的質(zhì)量和穩(wěn)定性。

這里可以參看我之前給大家分享的《嵌入式開(kāi)發(fā)中測(cè)試用例怎么寫？》

5、維護(hù)文檔

我們軟硬件開(kāi)發(fā)過(guò)程，以及后續(xù)更新都有不同版本，維護(hù)文檔主要是記錄了嵌入式系統(tǒng)的維護(hù)過(guò)程、常見(jiàn)問(wèn)題及解決方法等，有助于系統(tǒng)的長(zhǎng)期穩(wěn)定運(yùn)行和故障排查。

6、其他文檔

上面是我們嵌入式項(xiàng)目常見(jiàn)的有必要寫的一些文檔，如果大一點(diǎn)的公司，可能還存在其他一些文檔，比如：總結(jié)文檔、部署文檔、用戶手冊(cè)文檔等。

總結(jié)

以上只是“大框架"，具體如何實(shí)現(xiàn)與公司管理、項(xiàng)目等多方面因素都有關(guān)，但一個(gè)原則，把文檔的主要內(nèi)容描述清楚即可。

寫文檔可能是工程師比較討厭的事情，但從項(xiàng)目長(zhǎng)遠(yuǎn)來(lái)看，或者說(shuō)從自生長(zhǎng)遠(yuǎn)的職業(yè)發(fā)展來(lái)說(shuō)，寫文檔還是很有必要。

最后，你們開(kāi)發(fā)過(guò)程中，有寫文檔嗎？