上篇聊了团队协作跨职能沟通的核心是信息共享。而文档是信息共享最持久、最可规模化的方式。今天单独拿文档能力出来深入聊因为这是一个被严重低估的工程师能力。很多工程师觉得代码写得好就行了写文档是浪费时间。这个想法在职业生涯早期可能没太大影响但越往上走文档能力的短板就越明显。为什么文档能力是隐藏加分项因为文档是技术影响力的放大器。你写了一个很巧妙的算法如果只存在你的代码里只有你和你身边的两三个同事知道。但如果你把它写成一篇技术文档全公司、甚至全行业的人都能受益。反过来那些在技术社区有影响力的人往往不是技术最强的人而是最能表达和传播的人。工程师常见的文档类型在机器人项目中工程师需要写的文档大致分四类设计文档面向开发团队内部记录架构决策、技术方案、接口定义。这类文档的读者是同事和未来的自己。写好设计文档的关键是说清楚为什么——不只是我做了什么还要说我为什么这么做、考虑了哪些替代方案、为什么放弃了它们。半年后你自己回头看代码如果没有设计文档你也会忘记当初为什么选了那个方案。操作手册面向使用者包括运维人员和客户。写操作手册的诀窍是假设读者完全不懂技术用第一步、第二步这种傻瓜式步骤配上截图。每个操作都要说清楚预期结果——运行这条命令后你应该看到绿色的OK字样。问题排查文档Troubleshooting Guide面向运维和售后。记录已知的问题现象、可能原因、排查步骤和解决方案。这是使用频率最高的文档类型之一但往往是最不完整的。建议每修一个线上bug就把排查过程记录到Troubleshooting Guide里。API文档面向调用你代码的人。这个在第333篇详细聊过这里不再展开。写文档的核心原则好的技术文档有几个共同特点结构清晰先说结论。工程师写文档最容易犯的毛病是按自己思考的顺序写——先说背景、再说分析、再说方案、最后说结论。但读者最想知道的是结论。用倒金字塔结构结论→依据→细节。读者如果需要细节会往下读不需要的话看结论就够了。一段一个主题。不要在一个段落里混杂多个话题。每个段落有且只有一个主题段落的开头就是这个主题的核心论点。这样读者可以快速扫描——只看段落开头就知道文档在说什么感兴趣的部分再细读。用具体例子代替抽象描述。延迟要尽量低是废话控制回路的端到端延迟必须低于20毫秒其中传感器采集到执行器响应的管道延迟不超过5毫秒才是有用的信息。文档里的每个关键描述都应该有具体的数字或例子支撑。代码示例比文字描述更有效。解释一个API怎么用写三段文字不如给一段能跑通的代码。但代码示例一定要完整——包括import语句、初始化代码、错误处理让读者复制粘贴就能跑。举个对比例子。不好的文档会这么写使用NavigationGoal消息发送导航目标。——一句话完事读者还是不知道怎么调。好的文档会给一段能直接跑的代码from nav2_msgs.action import NavigateToPose goal NavigateToPose.Goal() goal.pose.header.frame_id map goal.pose.pose.position.x 5.0 goal.pose.pose.position.y 3.0 goal.pose.pose.orientation.w 1.0 # 发送到action server等待结果 client.send_goal_async(goal)注意pose的frame_id必须是map否则导航会失败。这种细节只有踩过坑的人才会写出来也正是文档最有价值的部分。文档工具链工欲善其事必先利其器。机器人团队常用的文档工具链Markdown是基础。GitHub/GitLab的README、Confluence的页面、技术博客——底层都是Markdown。掌握Markdown的基本语法配合一个顺手的编辑器VS Code、Typora都行写文档的效率会大大提升。SphinxBreathe适合C项目。Sphinx原生支持Python文档生成配合Breathe扩展可以处理C的Doxygen注释。ROS2的官方文档就是用Sphinx生成的。好处是文档和代码在同一套工具链里管理代码注释更新后文档自动更新。图表工具推荐draw.io或者PlantUML。架构图、流程图、时序图——这些图用文字描述效率极低但一张图就能说清楚。draw.io上手简单PlantUML可以用代码生成图表适合喜欢纯文本工作流的工程师。版本管理文档也不能少。README里要写清楚依赖版本、编译环境、构建步骤。很多项目换了个人来接手光搭环境就花了一天就是因为README里写的依赖版本已经过时了。我们团队有个小工具CI里会自动检查README中的构建步骤是否能在新环境里跑通——开一个全新的Docker容器按README的步骤操作一遍哪一步卡住了就说明文档需要更新了。对于面向外部开发者的文档比如SDK文档、开源项目的README要求比内部文档更高。外部开发者没有上下文背景不知道你的项目架构不知道你的内部约定所以每个细节都要交代清楚。好的开源项目文档通常包含Quick Start五分钟跑通Hello World、Installation安装依赖的详细步骤、API Reference完整的接口文档、Examples三到五个从简单到复杂的示例、FAQ常见问题解答。这五个部分缺一不可缺了任何一个都会让新用户的体验大打折扣。怎么培养文档习惯写文档最大的敌人不是不会写而是不想写。怎么克服把写文档变成开发流程的一部分而不是做完之后额外做的事。我们的做法是PR模板里包含是否更新了文档的检查项代码审查时如果发现接口变了但文档没更新审查不通过。从小处开始。不需要一上来就写十页的设计文档。先从README开始每个模块有一个README写清楚这个模块是做什么的、怎么编译、怎么运行。然后逐步扩展加了接口就写API文档做了重要决策就写设计文档。把文档当作代码一样对待。文档也要review也要版本管理也要定期清理过时内容。过时的文档比没有文档更有害——它给新来的人提供了错误的信息让人走弯路。面试追问你怎么看待文档和代码的关系文档是代码的补充不是替代品。代码告诉你怎么做文档告诉你为什么这么做和怎么正确使用。两者缺一不可。代码更新时文档必须同步更新否则文档就成了误导。你写过哪些技术文档我在项目中主要写三类文档模块的设计文档记录架构决策和关键算法的选择理由、API文档用Sphinx从代码注释自动生成、运维手册记录部署、配置、故障排查的流程。设计文档是我最重视的因为它直接影响团队的技术传承效率。怎么评估文档写得好不好两个标准一是新人看完文档能不能独立完成对应的工作不需要老员工手把手教二是三个月后你自己回头看还能不能快速理解当时的设计思路。如果两个标准都满足说明文档质量达标了。技术文档写作不是什么高深技能但它是一个典型的复利型能力。你写的每一篇好文档都在持续产生价值——帮助新同事快速上手、帮助团队减少沟通成本、帮助未来的自己回忆决策背景。短期看写文档是浪费时间长期看它是最划算的投资之一。如果你从现在开始有意识地提升文档能力三年后你会发现自己不仅文档写得更好了思维也变得更清晰了——因为写文档的过程就是强迫自己把模糊的想法变成清晰的表达。这个能力在任何技术岗位上都受益终身。我认识好几个工程师技术能力差不多但文档写得好的那个总是先被提拔为Tech Lead——因为他的方案能被更多人理解他的决策能被更多人信任。下一篇聊技术分享与演讲。有了文档能力作为基础怎么在团队内部做Tech Talk把自己的知识和经验更广泛地传播出去。如果这篇文章对你有帮助欢迎点赞、在看、转发三连。 你的支持是我持续更新的最大动力。「机器人软件开发面试·从入门到精通」连载系列上一篇第339篇 团队协作实践——跨职能团队的沟通与配合下一篇预告第341篇 技术分享与演讲——如何在团队内做Tech Talk有任何问题欢迎评论区留言我会尽量回复。
第340篇 技术文档写作能力——工程师的隐藏加分项
上篇聊了团队协作跨职能沟通的核心是信息共享。而文档是信息共享最持久、最可规模化的方式。今天单独拿文档能力出来深入聊因为这是一个被严重低估的工程师能力。很多工程师觉得代码写得好就行了写文档是浪费时间。这个想法在职业生涯早期可能没太大影响但越往上走文档能力的短板就越明显。为什么文档能力是隐藏加分项因为文档是技术影响力的放大器。你写了一个很巧妙的算法如果只存在你的代码里只有你和你身边的两三个同事知道。但如果你把它写成一篇技术文档全公司、甚至全行业的人都能受益。反过来那些在技术社区有影响力的人往往不是技术最强的人而是最能表达和传播的人。工程师常见的文档类型在机器人项目中工程师需要写的文档大致分四类设计文档面向开发团队内部记录架构决策、技术方案、接口定义。这类文档的读者是同事和未来的自己。写好设计文档的关键是说清楚为什么——不只是我做了什么还要说我为什么这么做、考虑了哪些替代方案、为什么放弃了它们。半年后你自己回头看代码如果没有设计文档你也会忘记当初为什么选了那个方案。操作手册面向使用者包括运维人员和客户。写操作手册的诀窍是假设读者完全不懂技术用第一步、第二步这种傻瓜式步骤配上截图。每个操作都要说清楚预期结果——运行这条命令后你应该看到绿色的OK字样。问题排查文档Troubleshooting Guide面向运维和售后。记录已知的问题现象、可能原因、排查步骤和解决方案。这是使用频率最高的文档类型之一但往往是最不完整的。建议每修一个线上bug就把排查过程记录到Troubleshooting Guide里。API文档面向调用你代码的人。这个在第333篇详细聊过这里不再展开。写文档的核心原则好的技术文档有几个共同特点结构清晰先说结论。工程师写文档最容易犯的毛病是按自己思考的顺序写——先说背景、再说分析、再说方案、最后说结论。但读者最想知道的是结论。用倒金字塔结构结论→依据→细节。读者如果需要细节会往下读不需要的话看结论就够了。一段一个主题。不要在一个段落里混杂多个话题。每个段落有且只有一个主题段落的开头就是这个主题的核心论点。这样读者可以快速扫描——只看段落开头就知道文档在说什么感兴趣的部分再细读。用具体例子代替抽象描述。延迟要尽量低是废话控制回路的端到端延迟必须低于20毫秒其中传感器采集到执行器响应的管道延迟不超过5毫秒才是有用的信息。文档里的每个关键描述都应该有具体的数字或例子支撑。代码示例比文字描述更有效。解释一个API怎么用写三段文字不如给一段能跑通的代码。但代码示例一定要完整——包括import语句、初始化代码、错误处理让读者复制粘贴就能跑。举个对比例子。不好的文档会这么写使用NavigationGoal消息发送导航目标。——一句话完事读者还是不知道怎么调。好的文档会给一段能直接跑的代码from nav2_msgs.action import NavigateToPose goal NavigateToPose.Goal() goal.pose.header.frame_id map goal.pose.pose.position.x 5.0 goal.pose.pose.position.y 3.0 goal.pose.pose.orientation.w 1.0 # 发送到action server等待结果 client.send_goal_async(goal)注意pose的frame_id必须是map否则导航会失败。这种细节只有踩过坑的人才会写出来也正是文档最有价值的部分。文档工具链工欲善其事必先利其器。机器人团队常用的文档工具链Markdown是基础。GitHub/GitLab的README、Confluence的页面、技术博客——底层都是Markdown。掌握Markdown的基本语法配合一个顺手的编辑器VS Code、Typora都行写文档的效率会大大提升。SphinxBreathe适合C项目。Sphinx原生支持Python文档生成配合Breathe扩展可以处理C的Doxygen注释。ROS2的官方文档就是用Sphinx生成的。好处是文档和代码在同一套工具链里管理代码注释更新后文档自动更新。图表工具推荐draw.io或者PlantUML。架构图、流程图、时序图——这些图用文字描述效率极低但一张图就能说清楚。draw.io上手简单PlantUML可以用代码生成图表适合喜欢纯文本工作流的工程师。版本管理文档也不能少。README里要写清楚依赖版本、编译环境、构建步骤。很多项目换了个人来接手光搭环境就花了一天就是因为README里写的依赖版本已经过时了。我们团队有个小工具CI里会自动检查README中的构建步骤是否能在新环境里跑通——开一个全新的Docker容器按README的步骤操作一遍哪一步卡住了就说明文档需要更新了。对于面向外部开发者的文档比如SDK文档、开源项目的README要求比内部文档更高。外部开发者没有上下文背景不知道你的项目架构不知道你的内部约定所以每个细节都要交代清楚。好的开源项目文档通常包含Quick Start五分钟跑通Hello World、Installation安装依赖的详细步骤、API Reference完整的接口文档、Examples三到五个从简单到复杂的示例、FAQ常见问题解答。这五个部分缺一不可缺了任何一个都会让新用户的体验大打折扣。怎么培养文档习惯写文档最大的敌人不是不会写而是不想写。怎么克服把写文档变成开发流程的一部分而不是做完之后额外做的事。我们的做法是PR模板里包含是否更新了文档的检查项代码审查时如果发现接口变了但文档没更新审查不通过。从小处开始。不需要一上来就写十页的设计文档。先从README开始每个模块有一个README写清楚这个模块是做什么的、怎么编译、怎么运行。然后逐步扩展加了接口就写API文档做了重要决策就写设计文档。把文档当作代码一样对待。文档也要review也要版本管理也要定期清理过时内容。过时的文档比没有文档更有害——它给新来的人提供了错误的信息让人走弯路。面试追问你怎么看待文档和代码的关系文档是代码的补充不是替代品。代码告诉你怎么做文档告诉你为什么这么做和怎么正确使用。两者缺一不可。代码更新时文档必须同步更新否则文档就成了误导。你写过哪些技术文档我在项目中主要写三类文档模块的设计文档记录架构决策和关键算法的选择理由、API文档用Sphinx从代码注释自动生成、运维手册记录部署、配置、故障排查的流程。设计文档是我最重视的因为它直接影响团队的技术传承效率。怎么评估文档写得好不好两个标准一是新人看完文档能不能独立完成对应的工作不需要老员工手把手教二是三个月后你自己回头看还能不能快速理解当时的设计思路。如果两个标准都满足说明文档质量达标了。技术文档写作不是什么高深技能但它是一个典型的复利型能力。你写的每一篇好文档都在持续产生价值——帮助新同事快速上手、帮助团队减少沟通成本、帮助未来的自己回忆决策背景。短期看写文档是浪费时间长期看它是最划算的投资之一。如果你从现在开始有意识地提升文档能力三年后你会发现自己不仅文档写得更好了思维也变得更清晰了——因为写文档的过程就是强迫自己把模糊的想法变成清晰的表达。这个能力在任何技术岗位上都受益终身。我认识好几个工程师技术能力差不多但文档写得好的那个总是先被提拔为Tech Lead——因为他的方案能被更多人理解他的决策能被更多人信任。下一篇聊技术分享与演讲。有了文档能力作为基础怎么在团队内部做Tech Talk把自己的知识和经验更广泛地传播出去。如果这篇文章对你有帮助欢迎点赞、在看、转发三连。 你的支持是我持续更新的最大动力。「机器人软件开发面试·从入门到精通」连载系列上一篇第339篇 团队协作实践——跨职能团队的沟通与配合下一篇预告第341篇 技术分享与演讲——如何在团队内做Tech Talk有任何问题欢迎评论区留言我会尽量回复。