FDE Times 数据在招 FDE 职位 881▼8 近 7 天在招职位数的变化(同口径比较):不计入本周新开始追踪的公司的职位近 7 天新增 55在招公司 185支持远程 25%美国薪资中位数 $201k招聘最多 Databricks 98
ENVI

前线部署工程师(FDE)的专业媒体

书籍与课程

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

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

分享微博

要点速览

  • Google for Developers 于 2020 年 2 月 24 日免费推出 Technical Writing One 和 Two。每门课都分两部分:课前自学,以及有讲师带领的课堂环节。
  • 先学 One。它教你为对的读者写作、使用主动语态,让谁也不必去猜由谁来做。
  • Two 教你组织长篇文档、自我编辑,以及在写作中使用 LLM。写交接规格说明和 runbook 正需要这些技能。
2020 年至 2024 年时间线:2020 年 2 月 24 日,Google 发布 Technical Writing One 和 Two 两门课;2020 年 7 月 9 日,Google Developers Blog 文章指出好文档帮助工程师独立工作;2022 年 3 月,tcworld 报道技术写作者短缺,工程师只能自己写文档;2024 年 4 月 15 日,Technical Writing Two 为每个练习加入总结幻灯片,这是突出显示的节点。
两门课于 2020 年推出,最近一次更新在 2024 年。资料来源:Google for Developers 官方更新日志、Google Developers Blog(James Scott)、tcworld(Dirk Göhmann)。

设想交接邮件里有这样一句话:“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 个信源
路线图上的下一篇 · 阶段 4: 客户工作一本 1988 年的销售书,告诉 FDE 客户愿为哪些问题买单Neil Rackham 观察了 35,000 多次销售拜访,总结出如何用提问把客户的抱怨变成值得投入的需求。