作者 |strongerHuang

微信公众号 | strongerHuang

写文档对于嵌入式工程师来说“很难”，特别是一个项目有数十个文档要写的情况下。

那么，你们平时开发嵌入式项目，会写文档吗？一般要写多少个文档？哪些类型的文档？

有的公司做一个嵌入式项目，从头到尾没有一个文档，都是口头对接。而有的公司，开发一个嵌入式项目，文档有上百份。

我曾经开发过0文档的项目，也有五、六十份文档的项目（当然，不全是我写的，我只写了其中几份）。

你会发现，嵌入式项目到底要不要写文档，与公司性质、管理、项目大小等有关系。

一般来说，小公司人员不足、管理也不完善，不看重文档。反之，大公司不管项目大小，都有严格的规范，该有的文档一份不会少，即便文档内容不多。

严格来说，没有文档的嵌入式项目不是好的项目。

为什么这么说，相信很多读者都接手过“烂项目”，比如前两天给大家分享的《单片机项目中太多全局变量有什么弊端？》。其实，很多烂项目有一部分原因就是因为没有文档造成的。

那么，我们站在开发者的角度，你考虑过有必要写的文档有哪些吗？下面分享一下。

1、需求文档

需求文档很关键，所有的后续研发工作都是基于需求而来，它详细描述了嵌入式系统的功能需求、性能需求、接口需求等。并且助于确保开发团队对项目的理解保持一致，并作为后续设计和开发工作的基础。

需求文档在于确定项目的具体目标、功能需求以及性能指标。分析项目的复杂性和可行性，确保所选单片机、各种器件能够满足需求等。

如果公司人员多、细分工作的话，需求文档应该有多个。

2、设计文档

设计文档包括结构设计文档、硬件设计文档、软件设计文档等。

结构设计文档包含结构尺寸、大小、外观等内容，硬件设计文档描述包含嵌入式系统的硬件架构、电路板设计、元件选择等内容；软件设计文档则涉及软件架构、模块划分、接口定义等。

这些文档有助于团队成员理解系统的整体结构和各个部分的功能。

3、开发文档

这里开发文档，也是实现文档。这一部分文档应该是开发者写的最多的，主要是详细描述、记录了嵌入式系统的具体实现过程，包括源代码、头文件、库文件等。

这些文档对于后续的代码维护和升级至关重要，也有助于团队成员之间的代码共享和协作。

你会发现，有时候软件和硬件存在互相甩锅的情况。

4、测试文档

测试文档包括测试计划、测试用例、测试报告等。

详细描述了测试的过程、结果和问题分析，有助于确保嵌入式系统的质量和稳定性。

这里可以参看我之前给大家分享的《嵌入式开发中测试用例怎么写？》

5、维护文档

我们软硬件开发过程，以及后续更新都有不同版本，维护文档主要是记录了嵌入式系统的维护过程、常见问题及解决方法等，有助于系统的长期稳定运行和故障排查。

6、其他文档

上面是我们嵌入式项目常见的有必要写的一些文档，如果大一点的公司，可能还存在其他一些文档，比如：总结文档、部署文档、用户手册文档等。

以上只是“大框架"，具体如何实现与公司管理、项目等多方面因素都有关，但一个原则，把文档的主要内容描述清楚即可。

写文档可能是工程师比较讨厌的事情，但从项目长远来看，或者说从自生长远的职业发展来说，写文档还是很有必要。