紧急发布说明：如何在真实的时间压力下动笔写作
阅读约 1 分钟
大多数发布说明都是在代码完成之后写的，从容地经过审查，并按照一个和任何人有多迫切需要读到它 毫无关系的时间表发布。紧急发布、安全补丁、数据丢失的 bug、故障修复，会同时把所有这些条件都 颠倒过来：说明必须在大多数人通常才刚开始动笔之前就存在，几乎得不到审查，而且读它的是焦虑的 读者，不是从容的读者。如何写发布说明讨论的是正常 流程；这篇讨论的是当没有时间遵循它时，情况会有什么变化。
即便别的都做不到，紧急发布说明必须做对的那一件事是什么
在没有任何前置铺垫的情况下，用第一句话说清楚读者是否需要采取行动。一个遇到由事故触发的说明 的读者，往往已经因为从状态页面、支持工单或者自己的用户那里听说了这个问题而感到担忧。在行动 项之前先给出背景的说明，读起来就像是在恰恰最不该保留信息的情况下保留了信息。“无需采取任何 行动，这修补了一个不需要用户数据就能被利用的漏洞”和”请立即更新：这次发布修复了一个可能把 一个账户的数据展示给另一个账户的 bug”，两句都只有一句话，也都在焦虑的读者读到别的任何内容 之前，完成了她需要的全部工作。
当没有时间去做时，平常的编辑还适用吗
压缩的本能会一直存在，即使通常产生这种压缩的多轮草稿流程并不存在。重写 描述的是把一份啰嗦的初稿削减到它的本质；在时间压力下，往往根本没有初稿可供削减，这意味着这 种纪律必须在写作过程中就在脑子里运作，而不是作为之后的一个独立步骤。最快的方法是：写下你会 对一个问”我需要知道什么”的人大声说出来的那句话，然后停笔，因为那句话通常既是最快能写出来 的，也是那个状态下的读者真正会去处理的唯一一句。
| 常规发布说明 | 紧急发布说明 |
|---|---|
| 在代码审查之后、发布之前写成 | 常常和修复同步写成，在完整审查之前 |
| 为在多条目中快速浏览而优化 | 为在压力下被单独阅读的一条目而优化 |
| 可以把细节留给关联的体验日志 | 必须把最重要的事实放在最前面 |
| 铺垫和背景是受欢迎的 | 行动项之前的铺垫读起来像是在拖延 |
在真正确定问题原因之前发布一份说明，有时候可以吗
可以，前提是这份说明对那种不确定性诚实，而不是暗示一种你并不拥有的确定感。“我们已经为结账 环节错误率上升部署了一个修复；我们仍在确认根本原因，并会更新这份说明”是站得住脚的，也正确地 争取了时间；一份声称了某个你实际上并未确认过的具体原因的说明，是那种如果后来证明错了，人们 会反过来引用给你看的猜测。这里重要的纪律不是诊断的速度，而是永远不让说明的确定感超过团队真 实的确定感，因为紧急说明里一个错误的技术性断言，比承认的无知更损害信任。
过度自信、未经验证:
"Fixed: a race condition in the payment webhook handler
caused duplicate charges."
在时间压力下的诚实:
"已修复：部分客户曾就同一笔订单被重复扣款两次。我们
已经阻止了新的发生，并在 24 小时内为受影响的账户
退款。正在调查根本原因。"紧急说明应该提到问题的原因吗，还是只说它已经被修复了
说清楚修复了什么，以及读者应该做什么；把根本原因留给一份后续说明，等它真正被查明，而不是被 猜测出来的时候再写。身处事故当中的读者恰好想要两个事实：这件事是否已经解决，以及这件事是否 影响到我，而根本原因的解释，即便是准确的，也会在最不该失去这两个事实和注意力的时刻和它们 争夺注意力。事后分析报告在调查完成后单独发布，那才是根本原因该出现的地方；在时间压力下把 这两份文档混在一起，只会产生一份写得更慢、读起来也更慢的说明，恰恰是紧急情况所需要的东西的 反面。
移动应用强制更新的问题在这里也适用吗
同样的原则适用，只是被压缩得更厉害。移动应用的发布说明 讨论了强制更新，那里说明必须在别的任何内容之前先说明理由和截止日期，因为读者已经因为没有 选择而感到恼火了。网页上的紧急说明通常对读者来说是可选的，意思是她可以选择是否据此采取行动， 但同样的”先说明约束条件”的本能仍然适用，只是原因不同：不是恼火，而是紧迫感。
如何避免让紧急说明读起来像是在承认过错，尽管它不应该是这样
描述修复及其效果，而不是错误本身，并克制过度道歉的冲动，那对想要上面那两个事实的读者来说 读起来就像是废话。“我们发现并修复了一个影响部分导出功能的 bug”陈述了发生了什么，而没有给 它添加戏剧性；“我们对给尊贵客户带来的这个严重问题深表歉意”把有用的信息整整推迟了一句话， 只为了传达一个读者并没有要求的情感时刻。简洁而基于事实的说明并不冷漠，它是对读者真实状态 的尊重，而在真正的压力之下，那种状态是不耐烦，而不是需要被安抚。
FAQ
紧急发布说明应该经历和常规说明一样的审查流程吗? 应该是更轻量的，而不是完全没有：一位快速审查者，确认说明没有夸大确定性，这值得花上它所需 的那几分钟，因为一个未经审查的技术性断言出错的风险更高，恰恰是因为它写得很快。
在没有链接到更多细节的情况下发布一份紧急说明可以吗? 只能暂时如此。没有链接的说明作为最先发布的内容是可以的；一旦状态页面或后续说明中有任何一 个存在，就添加一个链接过去，因为想要比你给出的那一句话更多信息的读者，需要一个可以去的地方， 即便那个地方只是说”更多细节即将发布”。
紧急说明是否有时应该完全被省略，让修复悄悄地上线? 只在没有任何读者能够注意到或受到影响的问题上才可以这样做；如果有可能读者曾经历过这个问题， 说明就是告诉她这件事已经结束的东西，而沉默读起来就像这个问题可能仍然是活跃的。
事故解决之后，紧急说明应该被置顶或保持显眼多久? 直到那种即时的焦虑窗口关闭为止，通常是一两天，之后它就可以像其他任何条目一样折叠进常规的 体验日志里；一份置顶了好几个星期的说明，开始读起来像是一个尚未解决的担忧，而不是已经解决的。
本文的技术内容未经独立审核。如有错误，请告诉我们，我们会更正。