做软件的人：“工作体验好，好事才能来。”
双十一后第一天，阿里云崩了
从下图能看出，这次虽然只崩了3个多小时，但受影响的产品多，地域广。如图1。
图1 这次崩了受影响的产品多，地域广
应该说，阿里云的健康状态页设计得还是很不错的。
我很快就能找到这次崩了的持续时长，以及所影响的产品和地域。点赞！
我在8月3日发过一篇知乎想法，对比了阿里云从2018到2022年这5年来，崩得很严重的3次生产事故复盘报告对比图。如图2。 
图2 阿里云从2018到2022年这5年来，崩得很严重的3次事故复盘报告对比图
相信阿里云这次崩了后，很快也会发布一份详细的“事件说明”。
但……
阿里云崩了，我们更愿意读“事件说明”还是“避坑指南”？
相比浮于表面的事件说明，我更愿意读避坑指南。
首先我是做软件的。搞了30年的开发、测试、运维、管理和咨询。
对于做软件的人来说，能从软件行业的意外事件中学习到如何避坑，效果肯定比只学习“最佳实践”好。因为前者更加生动和有趣。
有人会说，阿里云的大部分用户，都不是做软件的呀。他们肯定不愿意看避坑指南。
我认为不做软件的阿里云用户，也愿意读避坑指南。
因为他们读了一份写得好的避坑指南，就相信阿里云已经从意外事件中学到了，并在将来可以成功避坑，从而继续保持对阿里云服务的信心。
那该如何写一份好的避坑指南？
好的避坑指南的原则，是“写的人愿意写，读的人愿意读”。
避坑指南，一般由意外事件当事人来写。如果她/他觉得意外事件让自己很难堪，还愿意把细节写出来吗？
如何让写避坑指南的当事人不觉得难堪呢？
方法很简单，第一步就是把原先的”生产事故复盘报告“，改名为”意外事件避坑指南“。
“生产事故复盘”报告包含“事故”这样的负面字眼，有自恋倾向的意外事件当事人，就不愿在报告中详细描述自己的失误，也不愿将报告分享给其他团队成员和用户。
这增大了其他成员将来踩进同样的坑的风险，也让用户对IT产品丧失信心。
因为“意外事件“比”生产事故“更加温和和中性，此时将“生产事故复盘报告”，改名为“意外事件避坑指南”，能强调报告可以帮助队友避免踩坑，也能帮助用户重树信心。
因为可以帮助他人，这样能让撰写和传播避坑指南的人，感觉更愉悦。而不会像“事故”报告那样，感觉丢了面子。如图3。
图3 因为可以帮助他人，这样能让撰写和传播避坑指南的人，感觉更愉悦；而不会像“事故”报告那样，感觉丢了面子
盘点该如何写好“IT系统意外事件避坑指南”
当然，一份写得好的避坑指南，并不是只把标题从“事件说明”改为“避坑指南”那么简单。
如何把“事件说明”，转变为众人喜闻乐见的“避坑指南”呢？
三周前，语雀也有一次意外事件。他们很快就向上千万的用户，发布了事件说明（原标题是“故障公告”）。这一点很赞！
下面我以语雀的事件说明为例来说明如何转变（参见：关于语雀 23 日故障的公告）。
先说写得不好的避坑指南。注意这只是通用的写得不好的点。语雀有两点还是做得不错的。
写得不好的避坑指南
1 缺少上下文：只站在意外事件直接负责团队的角度撰写，缺乏像“存储系统所使用的机器类别较老，无法直接操作上线”这样描述的背景介绍，导致读者在阅读时，产生误解，难以理解。
2 使用术语且不做解释：避坑指南中使用了“Region”、“多副本容灾”、“两地三中心”等术语，但是没有解释，导致不是做软件的用户在阅读时，难以理解，进而对避坑产生怀疑。
3 缺乏意外事件确切的影响数据：只提到意外事件持续7个多小时，缺乏其他数据，导致难以判断事件所影响的用户范围等规模程度，也难以判断意外事件何时完全恢复。
4 缺乏触发因素的底层细节描述：只提供了意外事件的高层次描述，难以判断意外事件的最底层根本原因，比如难以了解“在升级中新的运维工具”具体出了什么bug，这难以在将来实现避坑。
5 缺乏意外事件恢复的细节描述：读者希望了解如何能缓解意外事件的影响的实际措施细节，比如数据恢复、数据校验和联调细节，以便学习和分析。
6 缺乏可验证的预防措施：“运维团队加强运维工具的质量保障与测试，杜绝此类运维 bug 再次发生”听起来不错，但是缺乏具体的可执行的措施，更缺乏可验证性，让读者怀疑是否能真正实现。
7 具有指责意味：在避坑指南中，提到“运维团队加强运维工具的质量保障与测试，杜绝此类运维 bug 再次发生”，这句话的潜台词是，运维团队没有做好工作，导致意外事件发生。这种指责会促使运维团队产生抵触情绪，会心里反问：“为何语雀不做异地双活？”，难以实现避坑。如图4。
8 分享范围有限：避坑指南只在内部分享，导致其他团队和用户无法学习和了解，无法重塑信心，也无法提供反馈。（语雀这一点做得较好）
9 延迟发表：避坑指南在意外事件发生后，经过了很久才发表，难以实现避坑。（语雀这一点做得较好） 
图4 这种指责会促使运维团队产生抵触情绪，会心里反问：“为何语雀不做异地双活？”，难以实现避坑
写得好的避坑指南
1 提供上下文：避坑指南中提供意外事件的背景介绍，包括语雀的用户规模、用户分布、用户使用场景、用户使用习惯、用户使用时段等，让读者能够更好地理解意外事件的影响范围。
2 解释术语：避坑指南中解释“Region”、“多副本容灾”、“两地三中心”等术语，让读者能够更好地理解意外事件。
3 提供意外事件确切的影响数据：避坑指南中提供意外事件的持续时长、影响用户数、影响用户比例、影响用户使用时长、影响用户使用频率等数据，让读者能够更好地理解意外事件的影响范围。
4 提供触发因素的底层细节描述：避坑指南中提供意外事件的底层细节描述，比如运维工具的 bug如何触发问题的过程，让读者能够更好地理解意外事件的根本原因。
5 提供意外事件恢复的细节描述：避坑指南中提供意外事件的恢复细节描述，比如数据恢复的过程、验证过程、验证结果等，让读者能够更好地理解意外事件的恢复过程。
6 提供可验证的预防措施：避坑指南中提供可验证的预防措施，比如存储服务器离线后可快速上线的预期时长、如何验证运维动作的灰度范围和灰度时长等，让读者能够更好地理解意外事件的预防措施。
7 不具有指责意味：明确系统设计改进已考虑用异地双活应对此类意外事件，没有个人或团队会因该事件而受到指责。重点关注“出了什么问题”，而不是“谁”导致了事件。旨在改善机制和系统，而不是惩罚个人。
8 分享范围广泛：将“关于语雀 23 日故障的公告”更名为“语雀23日意外事件相关避坑指南”，有助于让当事人放下难堪而愿意在避坑指南中分享事件细节，让其他团队能够学习和提供反馈。（语雀向千万用户发布公告这一点做得较好）
9 及时发表：避坑指南在意外事件发生后，一周之内及时发表，让其他团队能够及时学习，也能够及时提供反馈。（语雀这一点做得较好）
10 数据驱动结论：提出的所有结论均基于事实和数据。
11 提供图表辅助说明：以图表的形式提供更多有用的信息，以便为了向不熟悉该系统的读者提供背景信息。
12 简明扼要：避坑指南中的每个部分都是简明扼要的，没有冗余的信息，让读者能够更好地理解意外事件的影响范围。
要想了解更多如何写好避坑指南的内容，可以参考《Google SRE工作手册》第10章。里面给出了正反两个例子。
但是，需要说明一点，国外一般把IT系统意外事件“避坑指南”，称为postmortem，直译就是“验尸报告”，这个词就更加负面了。
我之前有段时间，也使用“验尸报告”这个字眼儿。但在学习了社会心理学后，了解到做软件的人的感受，就将其改称为“避坑指南”。
总结
阿里云崩了，相比浮于表面的事件说明，我更愿意读写得好的避坑指南。
写得好的避坑指南，能让企业内外所有做软件的人，从以往意外事件中学到经验教训；也能让IT系统的用户，重塑对系统的信心。
要想让避坑指南“写的人愿意写，读的人愿意读”，就需要营造一个不让意外事件当事人感到难堪的温和的环境，让她/他从自责中走出来，从而更愿意详细地进行分享，通过帮助他人，获得更好的内心体验。
营造这种环境的第一步，就是把标题从“事件说明”**改为“避坑指南”**。
之后，再参考上面提到的9个坏习惯和12个好习惯，编写好的避坑指南。
如果你喜欢这篇文章，欢迎点赞，并转发给身边有需要的人。 如果你有更好的方法，欢迎在留言区留言，和我讨论。