上周我完成了第一次真正意义上的，面向研发人员的技术写作培训。作为一只，在公共场合讲话紧张得要死的人类，整个过程，竟然自我感觉表现得很不错。培训后也收到了研发同事积极、鼓励的反馈。朋友们，我感觉自己膨胀了啊，飘了啊……
这么说，恐怕是有点臭屁啦。不过我也清楚知道，第一次尝试，难免会有这样那样的不足。抱持着想要做到更好的美好愿望，今天就来总结复盘一下——我相信，也一定会有下一次、又一次、再一次……的机会，值得期待。
经历
当我们终于圆满地实现了一个目标，再回过头审视它来时的轨迹，就会发现，没有一件事注定顺利。
从一份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 文档系统的工作环境部署及工作流程说明 | 技术传播
这次他们说好要“讲真的” | 传播
在座都别吵了，你们还有我 | 技术传播
睿齐
技术传播从业者
品牌内容策划
自由摄影师
自由撰稿人
汪力迪
公众号：techcomm / htstory
微信号：bgrichi
