如何写出用户真正愿意花时间读完的发布说明
阅读约 1 分钟 更新于
要写出用户真正会读的发布说明，每一条都只需回答一个问题：读者现在能做什么以前做不到的事，以及他们需要为此做什么。把带有截止日期的内容放在最前面，明确说出谁会受到影响，如果确实不需要任何操作就直接说”无需操作”，没有什么可说的版本就跳过不发。这个页面剩下的所有内容，都是这条规则的具体应用。
错误修复和性能改进。
每个产品都发过这样的说明。原因很少是懒惰：这正是发布说明由内部人员撰写时会出现的结果——他们已经在 diff 里泡了两个星期，早已看不出一个陌生人到底会关心其中的哪一部分。换一种更好的语气解决不了这个问题，只有回答那个问题才能解决。
发布说明应该包含什么
对于每一个值得一提的变化，发布说明应该说明读者现在能做什么、谁适用、他们必须做什么（包括”什么都不用做”），以及任何带截止日期的内容何时生效。不应该包含内部工单编号、只有团队自己才懂的组件名称，或者仅以版本号作为唯一标题。
| 应该包含 | 应该省略 |
|---|---|
| 用读者的语言描述的结果 | 用团队的语言描述的实现方式 |
| 谁受影响，按套餐、角色或 API 版本区分 | “部分用户” |
| 需要采取的操作，或”无需操作” | 沉默，读者会用最坏的情况来填补它 |
| 任何有截止日期的事项的具体日期 | 用版本号代替日期 |
| 指向说明文档的链接 | 指向 pull request 的链接 |
| 用户报告过的修复，以及被提高的限制 | 内部工单 id |
| 放在最后、每行一句的无趣部分 | 与新闻混在一起的无趣部分 |
发布说明和体验日志（changelog）条目之间的划分，正是让这份清单成立的原因：体验日志保留一切，因此说明才可以省略一些内容。每种条目类型的带注释示例，收集在发布说明示例里。
每一条发布说明都要回答的问题
读者现在能做什么以前做不到的事，以及他们需要为此做什么?
如果一条内容无法回答这个问题，它就该留在体验日志里，而不该出现在发布说明中。两半都很重要。前半部分是价值所在，后半部分则是团队最容易忘记的部分，也正是它缺失时会引来大量支持工单的部分。
后半部分真正发挥作用的两个例子：
- “现有的 webhook 会一直正常工作到 11 月 1 日。此后，未签名的负载将被拒绝。”
- “无需任何操作。现有的导出文件会在你下次打开时自动重新编码。”
第二个例子明确说出了”无需操作”。这句话每次都值得写，因为找不到它的读者会自动假设最坏的情况。
发布说明应该怎样排序
按照对读者造成的后果来排序，绝不要按系统内部哪个部分发生了变化来排序。按 API、仪表盘、移动端和基础设施分组，反映的是你的组织架构，而不是读者的问题。
- 破坏性变更和任何有截止日期的内容。 始终放在最前面，即使它很小。如果读者只读了一行就停下，那一定得是这一行。如果截止日期是服务下线，这条内容读起来就应该像一份停用通知。
- 他们会想要的新功能。 每段一条，把结果放在第一句里。
- 变得更好的地方。 被报告过的修复、被提高的限制、变慢的地方。
- 其余的一切，作为列表。 依赖更新、内部重构、细小的文案改动。每项一行。几乎没人会读这部分，但它仍然应该存在，因为需要它的那个人真的需要它。
重写示例
之前：
v4.2.0 修复了
POST /exports端点在高负载下偶尔返回 500 的问题。重构了导出 worker。将node-pg升级到 8.11。改进了 CSV 序列化器中的错误处理。
之后：
大型账户的导出不再失败。 拥有约 5 万行以上数据的账户在开始导出时可能会收到 500 错误，月末尤其频繁。这个问题已经修复，现在无论大小，导出都会在失败时自动重试，而不是直接失败。无需任何操作，过去一周内失败过的导出可以直接重新运行。
4.2.0 中的其他改动：
node-pg升级到 8.11，CSV 序列化器的错误信息更加清晰。
同一个版本。第二个版本说出了受影响的账户范围、最严重的时间段、发生了什么变化，以及该怎么做。依赖升级并没有消失，只是不再是标题。发布说明最佳实践一文列出了这次重写所遵循的其余规则，并说明了跳过每一条各自会付出什么代价。
值得删除的内容
- “我们很高兴地宣布。” 读者此刻还没有高兴的理由，让下一句话去赢得这种情绪。
- 内部工单编号。
PROJ-4471在你的追踪系统之外没有任何意义。如果确实需要一个参考，就链接到文档页面。 - 只有团队自己使用的组件名称。 如果你把”ingest pipeline”改名了，就说”导入”。
- 仅作为唯一标题的版本号。
v4.2.0只是一个归档标签，不是摘要。 - 没人访问过的设置页面截图。 展示实际改变了的东西正在被使用的样子。
发布说明应该多久发布一次
在有事发生时发布，而不是按固定的时间表发布。每个版本都发的说明，会训练所有人去忽略它。只在有事发生时才到达的说明，才会被打开。完全可以，也通常是正确的做法：发布一个不带任何说明的版本，把它的内容并入下一批真正有标题值得一读的说明中。
体验日志仍然会记录下这一切。这就是分工：体验日志是完整的，说明是经过挑选的。如果你在开发过程中始终把体验日志维护成结构化的样子，写说明就是挑选和重写的工作，而不是考古。
发布说明模板就是我们用来完成挑选这一步的形式，而体验日志范例收集了那些体验日志维护得足够好、足以从中提炼出说明的团队的条目。
以上这一切，默认前提都是一个你能完全掌控的页面，没有字数上限，链接也能正常点开。移动应用的发布说明 讲解了当这个界面变成一个 App Store 或者 Play Store 页面时，情况到底会有什么不同。 紧急发布说明 讲解了另一种例外情况：当完全没有时间遵循 正常写作流程时，情况到底会有什么不同。
发布前的一个测试
把自己当成一个休假两周、只有 40 秒时间的人，去读这份说明。如果在这段时间里，他判断不出自己需要做些什么，那么无论这份说明多么准确，它都还没有完成。
FAQ
发布说明应该有多长? 只需要和有实际后果的变化所需要的一样长，不要更长。一个版本里有一个破坏性变更和两个改进，三段就足够了。把一个平淡的版本硬凑得看起来很充实，正是读者学会跳过说明的原因。
发布说明应该由谁来写? 由理解这个变化的人来写，再由不了解它的人来编辑。工程师知道发生了什么变化；编辑知道陌生人会误解哪些地方。在合并代码时就趁工程师还记得细节把说明写下来，这个习惯让这一切变得便宜。
发布说明应该包含错误修复吗? 应该，只要是有人报告过或遇到过的问题。描述读者看到的症状，而不是原因。“超过 5 万行的导出会失败”是读者能认出的错误修复；“修复了导出 worker 中的一个竞态条件”是一条提交信息。
发布说明和体验日志的区别是什么? 体验日志是完整的、持续更新的记录；发布说明是关于某一个版本、经过挑选的信息，写给那些还没决定是否关心的人看。更完整的答案在体验日志与发布说明一文中。
本文的技术内容未经独立审核。如有错误，请告诉我们，我们会更正。