|
作者 | strongerHuang
微信公眾號 | strongerHuang
寫文檔對于嵌入式工程師來說“很難”,特別是一個(gè)項(xiàng)目有數(shù)十個(gè)文檔要寫的情況下。
那么,你們平時(shí)開發(fā)嵌入式項(xiàng)目,會寫文檔嗎?一般要寫多少個(gè)文檔?哪些類型的文檔?
這類問題也是讀者問的比較多的問題,今天就來簡單講講。
嵌入式項(xiàng)目到底要不要寫文檔?
有的公司做一個(gè)嵌入式項(xiàng)目,從頭到尾沒有一個(gè)文檔,都是口頭對接。而有的公司,開發(fā)一個(gè)嵌入式項(xiàng)目,文檔有上百份。
我曾經(jīng)開發(fā)過0文檔的項(xiàng)目,也有五、六十份文檔的項(xiàng)目(當(dāng)然,不全是我寫的,我只寫了其中幾份)。
shacotcb0ko64060825134.jpg (195.9 KB, 下載次數(shù): 8)
下載附件
保存到相冊
shacotcb0ko64060825134.jpg
2024-10-8 07:31 上傳
你會發(fā)現(xiàn),嵌入式項(xiàng)目到底要不要寫文檔,與公司性質(zhì)、管理、項(xiàng)目大小等有關(guān)系。
一般來說,小公司人員不足、管理也不完善,不看重文檔。反之,大公司不管項(xiàng)目大小,都有嚴(yán)格的規(guī)范,該有的文檔一份不會少,即便文檔內(nèi)容不多。
嵌入式項(xiàng)目需要寫哪些文檔?
嚴(yán)格來說,沒有文檔的嵌入式項(xiàng)目不是好的項(xiàng)目。
為什么這么說,相信很多讀者都接手過“爛項(xiàng)目”,比如前兩天給大家分享的《單片機(jī)項(xiàng)目中太多全局變量有什么弊端?》。其實(shí),很多爛項(xiàng)目有一部分原因就是因?yàn)闆]有文檔造成的。
那么,我們站在開發(fā)者的角度,你考慮過有必要寫的文檔有哪些嗎?下面分享一下。
iwxgomudu5h64060825234.jpg (142.21 KB, 下載次數(shù): 6)
下載附件
保存到相冊
iwxgomudu5h64060825234.jpg
2024-10-8 07:31 上傳
1、需求文檔
需求文檔很關(guān)鍵,所有的后續(xù)研發(fā)工作都是基于需求而來,它詳細(xì)描述了嵌入式系統(tǒng)的功能需求、性能需求、接口需求等。并且助于確保開發(fā)團(tuán)隊(duì)對項(xiàng)目的理解保持一致,并作為后續(xù)設(shè)計(jì)和開發(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、開發(fā)文檔
這里開發(fā)文檔,也是實(shí)現(xiàn)文檔。這一部分文檔應(yīng)該是開發(fā)者寫的最多的,主要是詳細(xì)描述、記錄了嵌入式系統(tǒng)的具體實(shí)現(xiàn)過程,包括源代碼、頭文件、庫文件等。
這些文檔對于后續(xù)的代碼維護(hù)和升級至關(guān)重要,也有助于團(tuán)隊(duì)成員之間的代碼共享和協(xié)作。
你會發(fā)現(xiàn),有時(shí)候軟件和硬件存在互相甩鍋的情況。
rv01powrwwz64060825334.jpg (203.76 KB, 下載次數(shù): 7)
下載附件
保存到相冊
rv01powrwwz64060825334.jpg
2024-10-8 07:31 上傳
4、測試文檔
測試文檔包括測試計(jì)劃、測試用例、測試報(bào)告等。
詳細(xì)描述了測試的過程、結(jié)果和問題分析,有助于確保嵌入式系統(tǒng)的質(zhì)量和穩(wěn)定性。
這里可以參看我之前給大家分享的《嵌入式開發(fā)中測試用例怎么寫?》
5、維護(hù)文檔
我們軟硬件開發(fā)過程,以及后續(xù)更新都有不同版本,維護(hù)文檔主要是記錄了嵌入式系統(tǒng)的維護(hù)過程、常見問題及解決方法等,有助于系統(tǒng)的長期穩(wěn)定運(yùn)行和故障排查。
6、其他文檔
上面是我們嵌入式項(xiàng)目常見的有必要寫的一些文檔,如果大一點(diǎn)的公司,可能還存在其他一些文檔,比如:總結(jié)文檔、部署文檔、用戶手冊文檔等。
總結(jié)
以上只是“大框架",具體如何實(shí)現(xiàn)與公司管理、項(xiàng)目等多方面因素都有關(guān),但一個(gè)原則,把文檔的主要內(nèi)容描述清楚即可。
寫文檔可能是工程師比較討厭的事情,但從項(xiàng)目長遠(yuǎn)來看,或者說從自生長遠(yuǎn)的職業(yè)發(fā)展來說,寫文檔還是很有必要。
最后,你們開發(fā)過程中,有寫文檔嗎?
------------ END ------------
11jm3oopt4j64060825434.gif (71.87 KB, 下載次數(shù): 7)
下載附件
保存到相冊
11jm3oopt4j64060825434.gif
2024-10-8 07:31 上傳
●專欄《嵌入式工具》●專欄《嵌入式開發(fā)》●專欄《Keil教程》●嵌入式專欄精選教程
回復(fù)“加群”按規(guī)則加入技術(shù)交流群,回復(fù)“1024”查看更多內(nèi)容。
點(diǎn)擊“閱讀原文”查看更多分享。 |
|