打印
[学习资料]

嵌入式项目需要写哪些文档?

[复制链接]
19329|24
手机看帖
扫描二维码
随时随地手机跟帖
跳转到指定楼层
楼主
elephant00|  楼主 | 2024-6-17 11:52 | 只看该作者 回帖奖励 |倒序浏览 |阅读模式
写文档对于嵌入式工程师来说“很难”,特别是一个项目有数十个文档要写的情况下。



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



这类问题也是读者问的比较多的问题,今天就来简单讲讲。

嵌入式项目到底要不要写文档?

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



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



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



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



嵌入式项目需要写哪些文档?

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



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



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



1、需求文档

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



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



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



2、设计文档

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



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



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



3、开发文档

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



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



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



4、测试文档

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


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



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



5、维护文档

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



6、其他文档

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



总结

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



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



最后,你们开发过程中,有写文档吗?

使用特权

评论回复
沙发
呐咯密密| | 2024-6-17 14:37 | 只看该作者
我没有写文档的习惯,但是我觉得文档很重要,有时候放个假回来我都不记得之前开发进度了。

使用特权

评论回复
板凳
储小勇_526| | 2024-6-17 16:47 | 只看该作者
文档确实很重要,但是没写过的开始写会很痛苦

使用特权

评论回复
地板
Siderlee| | 2024-6-17 20:30 | 只看该作者
一个流程管理严格的公司,文档是最重要的资源
AI的回答:

在嵌入式项目中通常需要编写的文档:

项目需求规格说明书(Requirements Specification):
详细描述项目的目标、功能需求、性能需求、安全需求等。
作为项目开发的基础,确保所有团队成员对项目的目标有清晰的认识。
系统设计文档(System Design Document):
描述系统的整体架构、模块划分、接口定义等。
展示系统的硬件设计、软件设计以及它们之间的交互方式。
硬件设计文档(Hardware Design Document):
包括电路图、PCB设计图、元件清单等。
描述硬件的原理、功能、性能指标等。
软件设计文档(Software Design Document):
描述软件的总体结构、模块功能、算法设计、数据结构等。
可以包括流程图、状态图、UML图等辅助说明。
用户手册(User Manual):
面向用户的操作指南,介绍产品的使用方法、注意事项等。
可以包括安装步骤、操作界面说明、故障排除等内容。
测试计划(Test Plan):
描述测试的目标、范围、方法、资源等。
制定测试用例和测试场景,确保产品的质量和性能。
测试报告(Test Report):
记录测试的执行过程和结果。
分析测试中发现的问题,提出改进措施。
维护手册(Maintenance Manual):
描述产品的维护方法、保养周期、故障排查步骤等。
为产品的售后服务提供支持。
项目进度报告(Project Progress Report):
定期向项目相关方报告项目的进展情况。
包括已完成的工作、未完成的工作、遇到的问题及解决方案等。
变更管理文档(Change Management Document):
记录项目过程中发生的变更请求、变更内容、变更影响等。
确保项目变更得到适当的评估和批准。
风险评估文档(Risk Assessment Document):
分析项目中可能存在的风险,如技术风险、市场风险、供应链风险等。
提出相应的风险应对策略和措施。
项目总结报告(Project Summary Report):
在项目结束后,对整个项目进行回顾和总结。
分析项目的成功之处和不足之处,为未来的项目提供参考和借鉴。

使用特权

评论回复
5
Siderlee| | 2024-6-17 20:32 | 只看该作者
在嵌入式项目中通常需要编写的文档:

项目需求规格说明书(Requirements Specification):
      详细描述项目的目标、功能需求、性能需求、安全需求等。
      作为项目开发的基础,确保所有团队成员对项目的目标有清晰的认识。
系统设计文档(System Design Document):
      描述系统的整体架构、模块划分、接口定义等。
      展示系统的硬件设计、软件设计以及它们之间的交互方式。
硬件设计文档(Hardware Design Document):
      包括电路图、PCB设计图、元件清单等。
       描述硬件的原理、功能、性能指标等。
软件设计文档(Software Design Document):
       描述软件的总体结构、模块功能、算法设计、数据结构等。
       可以包括流程图、状态图、UML图等辅助说明。
用户手册(User Manual):
       面向用户的操作指南,介绍产品的使用方法、注意事项等。
       可以包括安装步骤、操作界面说明、故障排除等内容。
测试计划(Test Plan):
       描述测试的目标、范围、方法、资源等。
       制定测试用例和测试场景,确保产品的质量和性能。
测试报告(Test Report):
      记录测试的执行过程和结果。
      分析测试中发现的问题,提出改进措施。
维护手册(Maintenance Manual):
        描述产品的维护方法、保养周期、故障排查步骤等。
        为产品的售后服务提供支持。
项目进度报告(Project Progress Report):
       定期向项目相关方报告项目的进展情况。
       包括已完成的工作、未完成的工作、遇到的问题及解决方案等。
变更管理文档(Change Management Document):
      记录项目过程中发生的变更请求、变更内容、变更影响等。
      确保项目变更得到适当的评估和批准。
风险评估文档(Risk Assessment Document):
      分析项目中可能存在的风险,如技术风险、市场风险、供应链风险等。
      提出相应的风险应对策略和措施。
项目总结报告(Project Summary Report):
      在项目结束后,对整个项目进行回顾和总结。
      分析项目的成功之处和不足之处,为未来的项目提供参考和借鉴。

使用特权

评论回复
6
Siderlee| | 2024-6-17 20:33 | 只看该作者
上面的内容没有提及结构设计
这个也很关键,应为很多的产品都是结构导向的

使用特权

评论回复
7
mbutterfly| | 2024-6-18 08:15 | 只看该作者
有文档可追溯,规范。

使用特权

评论回复
8
sleepybear| | 2024-6-18 08:48 | 只看该作者
写文档太重要了。不然,过一段时间,你自己都看不懂自己做过的东西。
写文档其实不难,想象自己是用户,自己需要得到什么信息?

使用特权

评论回复
9
lix1yr| | 2024-6-18 13:07 | 只看该作者
嵌入式项目通常需要编写一系列文档,以记录和规范项目的各个方面,确保开发过程的顺利进行、产品的质量和可维护性

使用特权

评论回复
10
lix1yr| | 2024-6-18 13:12 | 只看该作者
嵌入式项目通常需要编写一系列文档,以记录和规范项目的各个方面,确保开发过程的顺利进行、产品的质量和可维护性

使用特权

评论回复
11
liu96jp| | 2024-6-18 14:16 | 只看该作者
需求规格说明书,描述系统或产品的功能需求、性能需求、接口需求等。包括对输入输出、外部接口、数据处理、软件功能和非功能需求的详细描述

使用特权

评论回复
12
t1ngus4| | 2024-6-18 15:22 | 只看该作者
软件设计文档:描述软件架构、模块设计、数据流、算法等

使用特权

评论回复
13
g0d5xs| | 2024-6-18 16:26 | 只看该作者
描述硬件电路设计、接口定义、引脚分配、电源管理等

使用特权

评论回复
14
d1ng2x| | 2024-6-18 17:30 | 只看该作者
整合软硬件设计,描述系统的整体设计和互联互通。

使用特权

评论回复
15
ex7s4| | 2024-6-18 18:35 | 只看该作者
软件测试计划:描述测试策略、测试环境、测试工具和测试计划。测试用例(Test Cases):具体描述各个功能模块和系统的测试用例,包括输入数据、预期输出和实际输出的对比

使用特权

评论回复
16
cen9ce| | 2024-6-18 19:47 | 只看该作者
验证和验证报告:记录测试结果、缺陷报告和验证过程

使用特权

评论回复
17
zhizia4f| | 2024-6-19 07:43 | 只看该作者
用户手册和技术文档:用户手册(User Manual):面向最终用户,描述产品的使用方法、功能介绍、故障排除和安全说明。技术文档面向开发人员或技术支持人员,包括系统架构、接口定义、API文档、硬件连接图等详细技术资料

使用特权

评论回复
18
b5z1giu| | 2024-6-19 10:07 | 只看该作者
项目计划和进度报告:项目计划书(Project Plan):描述项目的整体规划、里程碑、资源分配和时间表。进度报告,定期更新项目进展、问题和风险,以及所采取的解决措施

使用特权

评论回复
19
q1ngt12| | 2024-6-19 11:13 | 只看该作者
维护文档和变更记录:维护手册,描述系统或产品的维护方法、版本控制、更新和修复的流程

使用特权

评论回复
20
lisasa| | 2024-7-10 16:23 | 只看该作者
最基本的文档:原理图,PCB,源代码,烧写体,SOP。

使用特权

评论回复
发新帖 我要提问
您需要登录后才可以回帖 登录 | 注册

本版积分规则

969

主题

2978

帖子

7

粉丝