一句被动句,让 SSL 证书没人续期
Google 两门免费技术写作课,教工程师写出客户团队不用回头打电话就能执行的交接文档。
要点速览
- Google for Developers 于 2020 年 2 月 24 日免费推出 Technical Writing One 和 Two。每门课都分两部分:课前自学,以及有讲师带领的课堂环节。
- 先学 One。它教你为对的读者写作、使用主动语态,让谁也不必去猜由谁来做。
- Two 教你组织长篇文档、自我编辑,以及在写作中使用 LLM。写交接规格说明和 runbook 正需要这些技能。
设想交接邮件里有这样一句话:“SSL 证书将在 15 日前完成续期。”读起来很干净。可到了 16 日,你的团队和客户团队可能同时发现,双方都以为续期不归自己管。
Google 在两门课里专门教工程师避开这类错误:Technical Writing One 和 Technical Writing Two。两门课都免费,放在 Google for Developers 上(developers.google.com/tech-writing)。你不必是专职技术写作者:课程面向软件工程师、计算机专业学生,以及产品经理等相关岗位。
想象一下:部署结束,你转去别的项目。规格说明、runbook 和交接邮件留了下来,客户团队只能靠你写下的东西来运维系统。如果这些文档逼得他们打电话来问你,这次部署就不算真正完成。
Google 为什么要教工程师写作?
Dirk Göhmann 在 2022 年 3 月发表于 tcworld 的文章里给出了一个直白的理由:文档需求远远超过技术写作者的数量。没有人替他们写,工程师只能自己动手。
技术写作者 James Scott 在 2020 年 7 月 9 日的 Google Developers Blog 文章中补充了另一点:随着远程办公普及,好文档更加重要,因为它能让工程师独立工作。
对前线部署工程师(FDE)来说,这一点更明显。客户团队需要答案时,写文档的人通常已经不在旁边解释了。
根据官方更新日志,两门课于 2020 年 2 月 24 日发布。Technical Writing Two 最近一次更新是 2024 年 4 月 15 日,为每个练习加了一页总结幻灯片。每门课分两部分:课前完成的自学课程,以及与讲师和其他学员一起进行的课堂环节。
Technical Writing One:两个值得记住的观点
Technical Writing One 是基础课,教你写出更清晰的技术文档。按课程介绍页的说法,你只需具备基本的英文写作能力。
第一个观点:按读者缺什么来界定读者。 讲受众的那一课强调,职位名称不足以描述读者。文档必须补上读者需要、但还不掌握的信息。课程还提醒,专家很容易忘记新手并不知道自己所知道的东西。
以客户那边两位职位相同的数据工程师为例。他们需要的文档未必一样:一位用过你选的消息队列,另一位从没用过。动笔之前,列出读者还不知道的三件事,再检查文档是否把这三件都讲清楚了。
第二个观点:使用主动语态。 讲主动语态的那一课建议以主动语态为主。原因是,有些被动句完全省掉了执行者,读者只能去猜由谁来做。本文开头那句 SSL 的话就是一例。改成“Minh 的基础设施团队在 15 日前续期 SSL 证书”,句子只多了几个字,却有了明确的负责人。
Technical Writing Two:面向长篇文档
Technical Writing Two 是进阶课,内容包括自我编辑、组织长篇文档、为插图写说明文字、写教程,以及新近加入的在写作中使用 LLM。Google 建议刚接触技术写作的人先学 One。
第三个观点来自组织大型文档那一课: 文档开头应说明它涵盖什么、读者需要事先了解什么、以及它不涵盖什么。以一份处理数据管道故障的 runbook 为例,开头可以这样写:本 runbook 说明如何重启卡住的 ingest 任务;读者需要会用 kubectl;不涉及源数据损坏的情况。
最后一句看起来像推脱,实际上很有用。它告诉值班工程师什么时候该停下、转去看另一份文档,而不是照着一套本来就不适用于当前情况的步骤操作。
学完课程后,人们还会在哪里出错?
最常见的错误是把句子改成主动语态,主语却依然含糊。“客户方续期证书”语法没问题,但读者还是得猜是哪个团队。只有当主语是大家都认得的具体团队或个人时,它才真正起作用。
其次是给所有同职位的人写同一份文档,这正是受众那一课提醒的陷阱。简单的解决办法:如果读者背景不同,把背景知识单独放一节,已经了解的人可以直接跳过。
第三个错误是写了开头,却怕文档显得不完整,省掉了“本文档不涵盖什么”这一句。想把三种错误都揪出来,就把草稿交给一位从没接触过这个系统的同事,记下对方每一处需要问你的地方。
应该按什么顺序学?
如果你是 FDE,或正准备转入这个岗位,先学 One,哪怕你觉得自己已经写得不错。每学完一课,马上用到一份真实文档上,不要攒到课程结束。Two 最适合在你即将写几页长的规格说明或交接文档时学。
写作也可以在求职时证明你的能力。改写一份旧 runbook,删去客户的机密信息,把修改前后两个版本放进作品集。在简历里写明这份文档帮助完成了哪项具体工作。
面试 FDE 岗位时,带上这两版 runbook。在带回家完成的笔试环节,提交一份开头三点齐全的 README。在系统设计面试中,被问到如何向客户交接时,打开修改后的版本,指出“不涵盖的情况”那一行。这比一句“沟通能力强”有说服力得多。
只有当客户团队不用给你打电话就能处理第一次故障时,部署才算真正完成。这两门课教你写出能做到这一点的文档。
这篇文章对你有帮助吗?
感谢你的反馈!
10 个信源
- Technical Writing Courses (Google for Developers)
- Technical Writing One (Google for Developers)
- Technical Writing Two (Google for Developers)
- Log of changes to technical writing courses · 2020-02-24
- Free technical writing courses (Google for Developers)
- Audience (Technical Writing One)
- Active voice (Technical Writing One)
- Organizing large documents (Technical Writing Two)
- Teaching the art of great documentation · 2020-07-09
- How (and why) Google teaches technical writing to engineers · 2022-03