# 一句被动句，让 SSL 证书没人续期

> Google 两门免费技术写作课，教工程师写出客户团队不用回头打电话就能执行的交接文档。

原文: https://fdetimes.net/zh/books-courses/google-technical-writing-courses-fde/

设想交接邮件里有这样一句话：“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。在系统设计面试中，被问到如何向客户交接时，打开修改后的版本，指出“不涵盖的情况”那一行。这比一句“沟通能力强”有说服力得多。

只有当客户团队不用给你打电话就能处理第一次故障时，部署才算真正完成。这两门课教你写出能做到这一点的文档。

**本周动手试试:**

- 打开最近一封交接邮件，找出所有没写明由谁执行的被动句，逐句改写，写上负责的团队或个人。
- 在一份正在使用的 runbook 顶部加三句话：本文档涵盖什么、读者需要先了解什么、本文档不涵盖什么。
- 完成 Technical Writing One 的自学部分，并立即用到一份真实的客户文档上。

## 信源

- [Technical Writing Courses (Google for Developers)](https://developers.google.com/tech-writing)

- [Technical Writing One (Google for Developers)](https://developers.google.com/tech-writing/one)

- [Technical Writing Two (Google for Developers)](https://developers.google.com/tech-writing/two)

- [Log of changes to technical writing courses](https://developers.google.com/tech-writing/for-instructors/release-notes)

- [Free technical writing courses (Google for Developers)](https://developers.google.com/tech-writing/announcements)

- [Audience (Technical Writing One)](https://developers.google.com/tech-writing/one/audience)

- [Active voice (Technical Writing One)](https://developers.google.com/tech-writing/one/active-voice)

- [Organizing large documents (Technical Writing Two)](https://developers.google.com/tech-writing/two/large-docs)

- [Teaching the art of great documentation](https://developers.googleblog.com/2020/07/teaching-art-of-great-documentation.html)

- [How (and why) Google teaches technical writing to engineers](https://www.tcworld.info/e-magazine/column/how-and-why-google-teaches-technical-writing-to-engineers-1172)
