嵌入式項目需要寫哪些文檔？

嵌入式專欄

作者 | strongerHuang
微信公眾號 | strongerHuang

寫文檔對于嵌入式工程師來說“很難”，特別是一個項目有數(shù)十個文檔要寫的情況下。

那么，你們平時開發(fā)嵌入式項目，會寫文檔嗎？一般要寫多少個文檔？哪些類型的文檔？

這類問題也是讀者問的比較多的問題，今天就來簡單講講。
嵌入式項目到底要不要寫文檔？
有的公司做一個嵌入式項目，從頭到尾沒有一個文檔，都是口頭對接。而有的公司，開發(fā)一個嵌入式項目，文檔有上百份。

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


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

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

嵌入式項目需要寫哪些文檔？
嚴格來說，沒有文檔的嵌入式項目不是好的項目。

為什么這么說，相信很多讀者都接手過“爛項目”，比如前兩天給大家分享的《單片機項目中太多全局變量有什么弊端？》。其實，很多爛項目有一部分原因就是因為沒有文檔造成的。

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


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

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

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

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

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

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

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

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

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

4、測試文檔
測試文檔包括測試計劃、測試用例、測試報告等。
詳細描述了測試的過程、結(jié)果和問題分析，有助于確保嵌入式系統(tǒng)的質(zhì)量和穩(wěn)定性。

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

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

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

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

寫文檔可能是工程師比較討厭的事情，但從項目長遠來看，或者說從自生長遠的職業(yè)發(fā)展來說，寫文檔還是很有必要。

最后，你們開發(fā)過程中，有寫文檔嗎？
------------ END ------------


●專欄《嵌入式工具》●專欄《嵌入式開發(fā)》●專欄《Keil教程》●嵌入式專欄精選教程
回復(fù)“加群”按規(guī)則加入技術(shù)交流群，回復(fù)“1024”查看更多內(nèi)容。
點擊“閱讀原文”查看更多分享。