上篇聊了版本管理，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或Sphinx+Breathe，Python用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篇 安全设计——机器人软件的功能安全和信息安全

有任何问题欢迎评论区留言，我会尽量回复。