写文档对于嵌入式工程师来说“很难”,特别是一个项目有数十个文档要写的情况下。
那么,你们平时开发嵌入式项目,会写文档吗?一般要写多少个文档?哪些类型的文档?
这类问题也是读者问的比较多的问题,今天就来简单讲讲。
嵌入式项目到底要不要写文档?
有的公司做一个嵌入式项目,从头到尾没有一个文档,都是口头对接。而有的公司,开发一个嵌入式项目,文档有上百份。
我曾经开发过0文档的项目,也有五、六十份文档的项目(当然,不全是我写的,我只写了其中几份)。
你会发现,嵌入式项目到底要不要写文档,与公司性质、管理、项目大小等有关系。
一般来说,小公司人员不足、管理也不完善,不看重文档。反之,大公司不管项目大小,都有严格的规范,该有的文档一份不会少,即便文档内容不多。
嵌入式项目需要写哪些文档?
严格来说,没有文档的嵌入式项目不是好的项目。
为什么这么说,相信很多读者都接手过“烂项目”,比如前两天给大家分享的《单片机项目中太多全局变量有什么弊端?》。其实,很多烂项目有一部分原因就是因为没有文档造成的。
那么,我们站在开发者的角度,你考虑过有必要写的文档有哪些吗?下面分享一下。
1、需求文档
需求文档很关键,所有的后续研发工作都是基于需求而来,它详细描述了嵌入式系统的功能需求、性能需求、接口需求等。并且助于确保开发团队对项目的理解保持一致,并作为后续设计和开发工作的基础。
需求文档在于确定项目的具体目标、功能需求以及性能指标。分析项目的复杂性和可行性,确保所选单片机、各种器件能够满足需求等。
如果公司人员多、细分工作的话,需求文档应该有多个。
2、设计文档
设计文档包括结构设计文档、硬件设计文档、软件设计文档等。
结构设计文档包含结构尺寸、大小、外观等内容,硬件设计文档描述包含嵌入式系统的硬件架构、电路板设计、元件选择等内容;软件设计文档则涉及软件架构、模块划分、接口定义等。
这些文档有助于团队成员理解系统的整体结构和各个部分的功能。
3、开发文档
这里开发文档,也是实现文档。这一部分文档应该是开发者写的最多的,主要是详细描述、记录了嵌入式系统的具体实现过程,包括源代码、头文件、库文件等。
这些文档对于后续的代码维护和升级至关重要,也有助于团队成员之间的代码共享和协作。
你会发现,有时候软件和硬件存在互相甩锅的情况。
4、测试文档
测试文档包括测试计划、测试用例、测试报告等。
详细描述了测试的过程、结果和问题分析,有助于确保嵌入式系统的质量和稳定性。
这里可以参看我之前给大家分享的《嵌入式开发中测试用例怎么写?》
5、维护文档
我们软硬件开发过程,以及后续更新都有不同版本,维护文档主要是记录了嵌入式系统的维护过程、常见问题及解决方法等,有助于系统的长期稳定运行和故障排查。
6、其他文档
上面是我们嵌入式项目常见的有必要写的一些文档,如果大一点的公司,可能还存在其他一些文档,比如:总结文档、部署文档、用户手册文档等。
总结
以上只是“大框架",具体如何实现与公司管理、项目等多方面因素都有关,但一个原则,把文档的主要内容描述清楚即可。
写文档可能是工程师比较讨厌的事情,但从项目长远来看,或者说从自生长远的职业发展来说,写文档还是很有必要。
最后,你们开发过程中,有写文档吗? |