复盘：第一次面向研发的技术写作培训 | 实践

上周我完成了第一次真正意义上的，面向研发人员的技术写作培训。作为一只，在公共场合讲话紧张得要死的人类，整个过程，竟然自我感觉表现得很不错。培训后也收到了研发同事积极、鼓励的反馈。朋友们，我感觉自己膨胀了啊，飘了啊……

这么说，恐怕是有点臭屁啦。不过我也清楚知道，第一次尝试，难免会有这样那样的不足。抱持着想要做到更好的美好愿望，今天就来总结复盘一下——我相信，也一定会有下一次、又一次、再一次……的机会，值得期待。

经历

当我们终于圆满地实现了一个目标，再回过头审视它来时的轨迹，就会发现，没有一件事注定顺利。

从一份2022年6月8日起草的改进建议中，第一次提到面向研发的技术写作培训开始，经历了几多波折，大多数时间看起来渺无希望，感恩贵人相助，总算跌跌绊绊地从无到有，从有到优地一路走来。

最终促成此次培训，得益于研发部门为了改进项目文档质量，痛下决心将输出文档写进了Q4季度的绩效考核，于是有研发部门主动提出，希望能够进行文档写作培训。

至此，那些曾经付出过看似徒劳的努力，才终于得到了一次施展的机会。

流程

回顾整个过程，大体可以分为准备阶段和实施阶段。

准备阶段

• 从培训目的和实现价值的角度说明培训计划，输出策划方案。

• 调研需求，尽可能多方地了解研发同事的意愿和需求，争取双向交流，避免单向宣讲。

• 梳理培训内容，并使用标准模板输出培训课件。

• 整个过程与培训经理经过一次评审，以及多次沟通，听取意见和建议，持续优化培训课件。

实施阶段

• 研发提出培训需求后，进行预演，确定课件和演讲稿。

• 按照预约时间，组织会议，实施培训。

• 培训后，汇总研发和培训经理反馈意见，进入下一轮迭代。

• 在接下来的1个月内，向研发提供技术写作支持和辅导。

策划方案

无论是培训方策划培训，还是受培方参与培训，都不得不在有忙碌的工作安排中加入额外的培训计划，付出巨大的时间成本，因此必须要充分考虑培训的目的和价值，甚至需要多角度考虑，说服相关方：这件事是值得做的。

培训目的  

• 了解公司对文档工作的期许。

• 了解技术文档基础知识。

• 了解对外交付文档开发协作和质量要求。

• 了解文档写作基本思路和写作风格。

• 了解文档问题支持方式。

培训收益

外部收益：

• 提升产品/文档的用户满意度

• 树立企业/产品形象，扩大品牌影响力

• 降低技术支持成本

内部收益：

• 降低文档开发成本

• 降低信息获取和学习成本

• 提高沟通效率

• 降低知识资产流失

个人收益：

• 提升沟通效率和效果

• 提升个人的行业影响力

• 提升职业发展基本技能

• 提升对思考过程的管理

• 有助于积累工作经验，扩大能力圈

培训目标人群

• 优先产品/研发部门新员工

• 产品/研发部门已有员工

培训情况

培训现场的情况大概是这样的：

• 面向对象：IC-SOC-后端设计

• 培训规模：预约10人，实际参加9人

• 培训时间：预计用时1.5小时；实际用时1.75小时

反馈意见

研发反馈形式：由培训经理事先准备在线培训反馈问卷，在培训后由受培人员填写。

研发反馈情况：参培人员9人；收集培训5条；回收率63%——据说还是不错的。

研发反馈：

• 培训组织的整体顺畅程度。平均分：4.8（5分满分，下同）

• 课程内容的专业程度。平均分：4.8

• 课程内容与实际工作的关联性。平均分：4.2

• 参与完培训，您觉得对团队工作的帮助有多大？平均分：3.6

• 本节课您的收获有哪些？1）案例分析；2）金字塔逻辑；3）写作风格；4）纠正了错误的文档写作观念。

• 诚邀您对本节课提出宝贵的建议，非常感谢！1）输出修正案例前后对比专题文章；2）提供针对IC开发过程中项目文档编写的培训。

培训经理反馈：

• 培训课程设计：培训内容以理论知识以及案例结合的方式进行分享，课程逻辑清晰。通过有机的设计吸引了学员的兴趣和注意力。学员的状态一直都比较在线。

• 课程内容改进点：案例需要贴合培训对象的实际场景会更好。迁移性的案例，学员接受程度会欠佳。

• 培训讲师：讲师速度流畅，给人专业和充分准备的感觉，对学员非常尊重。

• 讲师改进点：语速可以适当减慢，建议讲授技巧课程不带入立场，防止引导学员认为内容不完全适合自己、不具有通用性，吸收性会减弱。

• 总结：本节课在培训角度来看比较成功，讲师认真准备、课程设计合理，同时学员的兴趣有调动起来，通过调研反馈本次课程对一般同学实际工作帮助性较大。

总结

做的好的地方

培训经理主动推广课程——这一点必须要特别要提一下。如果不是培训经理从中多方沟通、识别需求、主动推广，单靠我一厢情愿地瞎搞，肯定是不行的啊。

预先识别文档写作培训需求，提前做好准备。在希望渺茫的时候，依然沟通寻找机会；在没有进展的时候，依然收集示例素材，完善课件……所以，当真实需求出现的时候，能够有充分信心接下来，并且完成得还不错。由此也充分地理解了那句话：机会是留给有准备的人。

演讲稿简洁明快，现场超水平发挥。话说，去年做过一次类似内容的线上分享，预先把演讲稿全篇写下来，现场照着念，效果并不好；这一次，每页PPT只标注了一些关键信息，包括场景举例、重点知识等，确保不会漏掉，具体的语言表达则完全依靠现场自由发挥，结果竟然还不错，神奇。

按照培训经理的指导，在表达观点时加入实际场景，增加可信度；增加案例说明，加深对知识的理解和运用。

充分思考并强调文档开发给到员工个人的好处，调动主观能动性。

待改进的地方

深度调研培训需求，避免无效内容。从培训策划的角度来看，原本是站在产品的立场上，面向新员工介绍产品文档相关事项来准备的；实际培训场景与预期有所不同。虽然识别到差异，但是没有进行针对性需求调研，所以部分内容存在立场偏差。

不要过分强调立场，聚焦通识、共性部分的分享。据培训经理反馈——我自己是没有意识啦——在培训过程中，我曾经多次提到自己是产品立场，潜意识里造成了与受培者的立场偏差。

避免罗列细节，尽量提炼为原则。课件中部分内容过于细节，再加上立场偏差，造成内容适用性不强。

聚焦项目文档，而不是产品文档，更容易在部门之间引起共鸣。

少一些理论，多一些用示例说话。

课件+演讲稿

最后，附上本次培训的课件和演讲稿。页数会比实际少一些，原因是，删除了一些包含内部信息的页面，或者考虑应该优化掉的页面。感兴趣的朋友可以了解一下，有好的想法和建议，也欢迎与我讨论。

• 面向主管推广课程的时候，聚焦企业价值；

• 面向员工进行课程培训的时候，聚焦个人收益。
  

• 文档很重要：介绍文档开发的目的和重要性。

• 文档什么鬼：介绍技术文档的基础知识和底层逻辑。

• 基本写作技巧：介绍文档写作的思路和写作风格。（重点）

• 文档技术支持：介绍本人可提供的文档写作相关技术支持。

举例：老板常常在主管级会议上拍桌强调“文档很重要”，为什么？

引文：开发者的文档纠结体质——讨厌写文档；讨厌别人不写文档——引发共鸣。

举例：写文档对“我”有什么好处？

举例：

• 外部场景：产品对外发布场景，客户首先查看文档，了解开发进度、测试场景、性能实现等，再决定是否试用软件。

• 内部场景：部门之间信息不对齐，造成目标不明确，问题后置，频繁返工等问题。

• 个人场景：上一天班，半天确认问题，半天做自己的事，做不完还要加班。

重点：说明对个人的好处。

举例：

• 研发同事主动表示：文档很重要，我要写文档。原因是：不写设计文档，不同人维护一套代码，会非常困难；不写用户文档，每天都要面对各方答疑，受不了。

• 建立个人IP，扩大个人影响力。

重点：行业发展对我们提出了更高的要求。

举例：

• 清华大学：面向本科学生开设写作与沟通课程。

• 百度技术培训中心：面向开发者开设工程能力系列培训课程，其中包括项目文档写作。
  

章节要点：

• 明确公司层面对文档工作非常重视。

• 理解文档的作用和重要性。

• 了解写作与沟通对个人成长和发展的重要性。

引文：作为技术文档的使用者，为什么有的文档写得好，有的文档写得不好，原因是什么？

介绍：技术文档的基础知识和底层逻辑。

误解：有同事说，你们语文学得好的，怎样怎样……

重点：技术文档看重思考、沟通和知识管理的逻辑；不看重文采。

介绍：

• 普通文档的内容通常前后信息关联大，需要读者顺序阅读；

• 技术文档采用“检索信息”式的阅读方式：

• 目的是：定向阅读，快速解决问题。

• 技术文档内容类型：

  • 说明类（Concept）：了解原理

  • 操作类（Task）：了解使用方法

  • 参考类（Reference）：了解详细信息

• 每个内容模块有一个主题

• 像搭积木一样，组织在一起

演示：Lyngor用户指南，介绍技术文档的使用方法。

重点：采用结构化的方式构建文档；避免信息顺序堆砌。

举例：参数说明，指定某配置文件。问：配置文件是给定的，还是需要用户自己配置？答：用户自己配置。问：那配置文件中的配置项，是不是要再展开介绍一下如何配置呀？答：用户看了自己就会配。

错误观点：假设用户全知全能；潜在风险是，可能有用户不知道如何配置，或者错误配置造成恶劣后果。

重点：

• 回显信息/错误码

• 配置文件

• 示例代码和说明

重点：

• 文档写作过程要有意识地输出警示信息。

• 尤其是，当我们的产品存在缺陷的时候。

重点：

• 文档开发的逻辑与代码开发的逻辑相同。

• 文档开发是伴随研发进程存在的。

• 重视文档设计阶段，可以有效避免问题后置造成的重构返工。（类比概要设计）

• 文档信息与代码实现是一一对应的。

章节要点：

• 了解文档基本构建逻辑（结构化），和内容类型（concept/task/reference）。

• 了解常见文档类型和常见用户接口。

• 了解对外交付文档开发协作流程和质量要求，以及目前已提供的文档资源。

错误观念：反正该写的我都已经写了，明白不明白是别人的事。

重点：具有产品思维，明确面向对象，实现信息目标。

重点：采用金字塔原理。

举例：

• 逻辑递进：全文构成

• 归类分组：硬件安装/软件安装/软件升级

• 以上统下：概述先行；详述展开

• 结论先行：举例因为什么原因，造成什么现象，所以用户应该怎样；修改为用户应该怎样，因为什么原因。

演示：文档样式导入和应用操作。

章节要点：

• 了解文档内容策划思路。面向对象，信息目标。

• 了解文档内容构建思路。金字塔模型。

• 了解常见内容写作要点：用户指南；接口说明；文档变更；常见问题。

• 了解基本写作风格。

• 了解如何使用样式模板。

其他推荐：

实施：GitHub + MarkDown 文档系统的工作环境部署及工作流程说明 | 技术传播

技术传播是一片蓝海 | 技术传播

访谈：TC无处不在，只是我们没有发觉 | 技术传播

这次他们说好要“讲真的” | 传播

在座都别吵了，你们还有我 | 技术传播

一本培养强迫症患者的说明书 | 技术传播

就像用心做好日本料理 | 技术传播

顽固的老头子与无聊的说明书 | 技术传播

转战新媒体 | 技术传播

评测：王者荣耀的用户帮助系统 | 技术传播

让爸爸妈妈也能享受到科技发展带来的便利 | 技术传播

企业级信息管理系统初创方案构思 | 技术传播

 

睿齐

技术传播从业者

品牌内容策划

自由摄影师

自由撰稿人

汪力迪

公众号：techcomm / htstory

微信号：bgrichi

邮箱：hash_0813@163.com