上篇聊了版本管理Git把代码管好了。但代码只是工程产出的一部分另一部分 equally important 的东西是文档。很多工程师觉得写文档是浪费时间代码不就是最好的文档吗——这话只对了一半。代码能告诉你怎么做但不能告诉你为什么这么做以及为什么不那么做。技术文档是工程知识的载体它让团队的认知不依赖于某一个人的大脑。面试时如果被问到你怎么做技术传承文档能力是一个很有说服力的回答。机器人项目的文档需求比纯软件项目更杂。你有算法设计需要写清楚推导过程有硬件接口需要写清楚电气参数有ROS节点之间的通信协议需要写清楚话题名和消息格式还有给终端用户看的操作手册。不同类型的文档有不同的写法混着来只会让所有人都看不懂。设计文档——记录决策过程设计文档Design Doc是在动手写代码之前写的。它回答三个问题我们要解决什么问题有哪些可选方案为什么选这个方案很多团队的设计文档只写了我们打算怎么做没有写为什么选这个方案和其他方案为什么被否决。半年后回头看当初选方案的原因早忘了新人接手时更是一头雾水。好的设计文档要把决策的上下文完整记录下来。一个实用的设计文档模板包含这些部分背景与问题描述、目标与非目标、方案对比表格形式最直观、详细设计架构图关键流程、风险评估、里程碑计划。不需要每个项目都写满所有部分小功能可以简化但方案对比和风险评估不能省。设计文档的读者是团队成员写的时候要考虑如果有人接手我的工作他能不能根据这份文档理解我的设计意图。语气不用太正式但逻辑必须严谨。数据要给来源假设要标明不确定的地方直接写待验证。我见过一个团队的模板设计文档写完要过设计评审会所有相关方都参加。评审会上最常问的问题是如果这个假设不成立怎么办和有没有更简单的方案。这两个问题往往能暴露设计文档里的薄弱环节。评审不是走过场而是用集体智慧帮你找漏洞。机器人项目的设计文档还有个特殊部分硬件依赖说明。你的软件依赖哪个型号的激光雷达、需要多大算力的计算平台、对通信延迟的容忍度是多少。这些约束条件不写清楚后面换硬件平台的时候就是灾难。API文档——让别人能用起来机器人项目里有大量的内部API感知模块输出的检测结果、控制模块接收的指令格式、各ROS节点之间的话题和服务。这些接口如果没有文档调用方就得去读源码才能搞清楚怎么用——效率极低。API文档的核心要素有四个输入是什么、输出是什么、异常情况怎么处理、给一个能跑通的示例。很多API文档只写了前两个忽略了异常处理和示例。结果调用方不知道传错参数会怎样只能靠试错来学习。ROS2的接口文档有个好的实践消息类型定义.msg/.srv/.action文件本身就是一种半文档化的格式。字段名、类型、注释都写在定义文件里。配合ros2 interface show命令可以直接查看接口定义。但这还不够——你还需要补充使用场景说明、参数的取值范围和物理含义、典型的使用示例。# 好的API文档示例 class ObstacleDetector: def detect(self, point_cloud: PointCloud2) - ObstacleArray: 检测点云中的障碍物。 Args: point_cloud: 标准ROS2点云消息 坐标系为base_laser 点密度不低于1000点/平方米 Returns: ObstacleArray每个障碍物包含 位置、尺寸、置信度、类别 Raises: ValueError: 点云为空或坐标系不匹配 工具方面C用Doxygen或SphinxBreathePython用Sphinx直接支持docstring生成。ROS2社区推荐使用rosdoc2它对ROS包的元数据支持更好。关键不在于用什么工具而在于养成改接口就更新文档的习惯。用户手册——站在用户的角度写用户手册和设计文档完全不同。设计文档面向开发者可以堆术语用户手册面向操作者必须用最简单的语言。机器人用户手册常见的问题有三个假设用户懂技术请确保ROS2环境已正确配置——用户连ROS是什么都不知道、只写正常流程不写故障排除机器人不动了怎么办、缺少安全注意事项哪些操作可能导致夹伤或碰撞。好的用户手册结构是这样的快速入门5分钟让机器人动起来→ 基本操作日常使用的完整流程→ 高级配置可调参数及其影响→ 故障排除常见问题及解决方案→ 安全须知操作红线。故障排除部分最容易被忽略但它恰恰是用户翻阅最多的章节。写故障排除的诀窍是从现象出发而不是从原因出发。用户看到的是机器人原地转圈不是IMU漂移导致航向角偏差。所以你应该写如果机器人原地转圈请检查以下三项。安全文档是机器人用户手册里不可或缺的部分。ISO 10218工业机器人安全标准和ISO 13482服务机器人安全标准都对用户文档有明确要求。你的手册里至少要包含安全操作区域标识、紧急停止方法、禁止操作清单、维护保养周期。这些内容不是写给律师看的免责条款而是真正能保护操作者安全的指南。写好的用户手册一定要做可用性测试——找一个没用过你机器人的人让他按手册操作你在旁边观察。你会发现很多你自己注意不到的问题某个步骤跳跃太大、某个术语用户不理解、某张图片角度不对看不清楚。这些细节只有真实用户才能暴露出来。文档维护——最容易被忽略的环节写文档不难难的是维护。代码在持续更新文档很容易就过时了。过时的文档比没有文档更可怕——它会给人错误的信心。几个实践能帮你保持文档更新把文档放在代码仓库里和代码一起review、一起更新、在CI里加文档检查比如API变更时必须有对应的文档变更、每次Sprint回顾时检查文档是否需要更新。还有个技巧写文档时标注最后验证日期。超过三个月没验证的文档就当它可能过时了使用前先确认一下。这比假装文档永远正确要靠谱得多。有个团队的做法值得借鉴他们在每个文档顶部加一个元数据区域写明作者、创建日期、最后验证日期、关联的代码版本。文档过期超过六个月没更新CI会自动给作者发邮件提醒。如果作者已经离职文档会被标记为待审核安排新人接手维护。文档不是写完就扔的它和代码一样有生命周期。面试追问你怎么保证文档和代码同步我们把文档放在代码仓库里和代码走同一个PR流程。API变更的PR必须同时更新文档否则code review不通过。CI里有脚本检测接口定义文件是否变更如果变更了但文档没改会发出提醒。设计文档写多详细合适看影响范围。影响架构的设计文档要详细到能让一个不了解项目的人实现出来。小范围的重构一页纸的设计说明就够了。有个判断标准如果你离开团队一个月别人能不能根据文档继续你的工作。你们用什么工具管理文档内部设计文档用Confluence或者Notion方便协作和搜索。API文档用Sphinx从代码自动生成。用户手册用Markdown写在仓库里CI自动发布到GitBook。关键不是工具而是每类文档有且只有一个权威来源。文档能力是工程师的隐藏技能树。很多技术很强的人因为文档写得差导致方案推不动、项目交接乱、个人影响力受限。反过来那些文档写得清晰的人往往更容易获得晋升机会——因为他们的思路能被更多人看到和理解。机器人项目的文档尤其重要因为系统复杂度高、涉及面广、安全要求严格。一个连操作手册都没有的机器人产品出了安全事故连责任都说不清楚。把文档当作产品的一部分来对待而不是有空再补的附属品。下一篇聊安全设计。机器人是物理世界的执行者软件bug不只是崩溃重启那么简单——可能造成人身伤害。功能安全和信息安全是机器人工程师必须建立的意识。如果这篇文章对你有帮助欢迎点赞、在看、转发三连。 你的支持是我持续更新的最大动力。「机器人软件开发面试·从入门到精通」连载系列上一篇第332篇 版本管理——Git在机器人项目中的最佳实践下一篇预告第334篇 安全设计——机器人软件的功能安全和信息安全有任何问题欢迎评论区留言我会尽量回复。
第333篇 技术文档写作——设计文档/API文档/用户手册的规范
上篇聊了版本管理Git把代码管好了。但代码只是工程产出的一部分另一部分 equally important 的东西是文档。很多工程师觉得写文档是浪费时间代码不就是最好的文档吗——这话只对了一半。代码能告诉你怎么做但不能告诉你为什么这么做以及为什么不那么做。技术文档是工程知识的载体它让团队的认知不依赖于某一个人的大脑。面试时如果被问到你怎么做技术传承文档能力是一个很有说服力的回答。机器人项目的文档需求比纯软件项目更杂。你有算法设计需要写清楚推导过程有硬件接口需要写清楚电气参数有ROS节点之间的通信协议需要写清楚话题名和消息格式还有给终端用户看的操作手册。不同类型的文档有不同的写法混着来只会让所有人都看不懂。设计文档——记录决策过程设计文档Design Doc是在动手写代码之前写的。它回答三个问题我们要解决什么问题有哪些可选方案为什么选这个方案很多团队的设计文档只写了我们打算怎么做没有写为什么选这个方案和其他方案为什么被否决。半年后回头看当初选方案的原因早忘了新人接手时更是一头雾水。好的设计文档要把决策的上下文完整记录下来。一个实用的设计文档模板包含这些部分背景与问题描述、目标与非目标、方案对比表格形式最直观、详细设计架构图关键流程、风险评估、里程碑计划。不需要每个项目都写满所有部分小功能可以简化但方案对比和风险评估不能省。设计文档的读者是团队成员写的时候要考虑如果有人接手我的工作他能不能根据这份文档理解我的设计意图。语气不用太正式但逻辑必须严谨。数据要给来源假设要标明不确定的地方直接写待验证。我见过一个团队的模板设计文档写完要过设计评审会所有相关方都参加。评审会上最常问的问题是如果这个假设不成立怎么办和有没有更简单的方案。这两个问题往往能暴露设计文档里的薄弱环节。评审不是走过场而是用集体智慧帮你找漏洞。机器人项目的设计文档还有个特殊部分硬件依赖说明。你的软件依赖哪个型号的激光雷达、需要多大算力的计算平台、对通信延迟的容忍度是多少。这些约束条件不写清楚后面换硬件平台的时候就是灾难。API文档——让别人能用起来机器人项目里有大量的内部API感知模块输出的检测结果、控制模块接收的指令格式、各ROS节点之间的话题和服务。这些接口如果没有文档调用方就得去读源码才能搞清楚怎么用——效率极低。API文档的核心要素有四个输入是什么、输出是什么、异常情况怎么处理、给一个能跑通的示例。很多API文档只写了前两个忽略了异常处理和示例。结果调用方不知道传错参数会怎样只能靠试错来学习。ROS2的接口文档有个好的实践消息类型定义.msg/.srv/.action文件本身就是一种半文档化的格式。字段名、类型、注释都写在定义文件里。配合ros2 interface show命令可以直接查看接口定义。但这还不够——你还需要补充使用场景说明、参数的取值范围和物理含义、典型的使用示例。# 好的API文档示例 class ObstacleDetector: def detect(self, point_cloud: PointCloud2) - ObstacleArray: 检测点云中的障碍物。 Args: point_cloud: 标准ROS2点云消息 坐标系为base_laser 点密度不低于1000点/平方米 Returns: ObstacleArray每个障碍物包含 位置、尺寸、置信度、类别 Raises: ValueError: 点云为空或坐标系不匹配 工具方面C用Doxygen或SphinxBreathePython用Sphinx直接支持docstring生成。ROS2社区推荐使用rosdoc2它对ROS包的元数据支持更好。关键不在于用什么工具而在于养成改接口就更新文档的习惯。用户手册——站在用户的角度写用户手册和设计文档完全不同。设计文档面向开发者可以堆术语用户手册面向操作者必须用最简单的语言。机器人用户手册常见的问题有三个假设用户懂技术请确保ROS2环境已正确配置——用户连ROS是什么都不知道、只写正常流程不写故障排除机器人不动了怎么办、缺少安全注意事项哪些操作可能导致夹伤或碰撞。好的用户手册结构是这样的快速入门5分钟让机器人动起来→ 基本操作日常使用的完整流程→ 高级配置可调参数及其影响→ 故障排除常见问题及解决方案→ 安全须知操作红线。故障排除部分最容易被忽略但它恰恰是用户翻阅最多的章节。写故障排除的诀窍是从现象出发而不是从原因出发。用户看到的是机器人原地转圈不是IMU漂移导致航向角偏差。所以你应该写如果机器人原地转圈请检查以下三项。安全文档是机器人用户手册里不可或缺的部分。ISO 10218工业机器人安全标准和ISO 13482服务机器人安全标准都对用户文档有明确要求。你的手册里至少要包含安全操作区域标识、紧急停止方法、禁止操作清单、维护保养周期。这些内容不是写给律师看的免责条款而是真正能保护操作者安全的指南。写好的用户手册一定要做可用性测试——找一个没用过你机器人的人让他按手册操作你在旁边观察。你会发现很多你自己注意不到的问题某个步骤跳跃太大、某个术语用户不理解、某张图片角度不对看不清楚。这些细节只有真实用户才能暴露出来。文档维护——最容易被忽略的环节写文档不难难的是维护。代码在持续更新文档很容易就过时了。过时的文档比没有文档更可怕——它会给人错误的信心。几个实践能帮你保持文档更新把文档放在代码仓库里和代码一起review、一起更新、在CI里加文档检查比如API变更时必须有对应的文档变更、每次Sprint回顾时检查文档是否需要更新。还有个技巧写文档时标注最后验证日期。超过三个月没验证的文档就当它可能过时了使用前先确认一下。这比假装文档永远正确要靠谱得多。有个团队的做法值得借鉴他们在每个文档顶部加一个元数据区域写明作者、创建日期、最后验证日期、关联的代码版本。文档过期超过六个月没更新CI会自动给作者发邮件提醒。如果作者已经离职文档会被标记为待审核安排新人接手维护。文档不是写完就扔的它和代码一样有生命周期。面试追问你怎么保证文档和代码同步我们把文档放在代码仓库里和代码走同一个PR流程。API变更的PR必须同时更新文档否则code review不通过。CI里有脚本检测接口定义文件是否变更如果变更了但文档没改会发出提醒。设计文档写多详细合适看影响范围。影响架构的设计文档要详细到能让一个不了解项目的人实现出来。小范围的重构一页纸的设计说明就够了。有个判断标准如果你离开团队一个月别人能不能根据文档继续你的工作。你们用什么工具管理文档内部设计文档用Confluence或者Notion方便协作和搜索。API文档用Sphinx从代码自动生成。用户手册用Markdown写在仓库里CI自动发布到GitBook。关键不是工具而是每类文档有且只有一个权威来源。文档能力是工程师的隐藏技能树。很多技术很强的人因为文档写得差导致方案推不动、项目交接乱、个人影响力受限。反过来那些文档写得清晰的人往往更容易获得晋升机会——因为他们的思路能被更多人看到和理解。机器人项目的文档尤其重要因为系统复杂度高、涉及面广、安全要求严格。一个连操作手册都没有的机器人产品出了安全事故连责任都说不清楚。把文档当作产品的一部分来对待而不是有空再补的附属品。下一篇聊安全设计。机器人是物理世界的执行者软件bug不只是崩溃重启那么简单——可能造成人身伤害。功能安全和信息安全是机器人工程师必须建立的意识。如果这篇文章对你有帮助欢迎点赞、在看、转发三连。 你的支持是我持续更新的最大动力。「机器人软件开发面试·从入门到精通」连载系列上一篇第332篇 版本管理——Git在机器人项目中的最佳实践下一篇预告第334篇 安全设计——机器人软件的功能安全和信息安全有任何问题欢迎评论区留言我会尽量回复。
