技术写作与文档2021onlineornot.com编辑精选
从 Fastly 宕机事件看如何写好错误信息
What the Fastly outage can teach us about writing error messages
导读
这篇文章借 Fastly 宕机时暴露在用户面前的错误页面，讨论错误信息应该怎么写：既要说明发生了什么、用户下一步能做什么，也要意识到不同读者（普通用户和开发者）需要的细节完全不同。对写作者来说值得一读，因为它把“受众意识”和“别让内部玩笑流到用户面前”讲得很具体。
可以直接用的写作要点
- 01
写错误信息前先问“谁会看到它”：普通用户要的是通俗说明和下一步操作，开发者要的是请求 ID 等能定位问题的线索，一段文案往往很难同时满足这两类人。
- 02
不要把你并不确定的原因写成确定结论，比如把认证失败一律写成“请先登录”；在无法确认真正原因时，宁可用中性描述加一个可追踪的编号。
- 03
默认信息宁可保守：只暴露一个能回溯日志的标识（如 XID），让能查日志的人去查细节，而不是把猜测直接写给用户。
- 04
不要在面向用户的文案和报错里塞俏皮话、内部梗，你以为是只有内部可见的错误，也可能原样暴露给外部读者。
HN 评论精选
错误信息要按读者分层，别把不确定的原因写成确定结论。
我在 AWS 做 principal，多年在 CloudFront 和 Route 53 上处理这类问题。这篇文章说对了很多，也有一点偏。我们确实应该告诉浏览者发生了什么、下一步该做什么，但有几个难题我还没见谁合理解决。第一个问题是不同浏览者需要不同上下文，对 CDN 这类服务商尤其如此。告诉终端用户“页面加载太慢”是合理的，但如果是 CDN 的客户（开发者），他们需要请求 ID 和其他诊断信息，就像 Fastly 展示的那样；事后玩“我们需要你提供你不知道的响应头里的 RID”这种游戏是必输的。文章举的“好”例子建议提供联系支持的途径，但没有额外信息，支持几乎不可能帮上忙。此外文章做了很危险的假设并带进文案语义里：把认证/授权失败暴露成 Access Denied 还是 Not Found 本身就各有问题；更进一步告诉用户“你需要先登录”，在那 10% 其实是凭证或授权问题的场景里就是自找麻烦。还是那句话，不同用户需要不同上下文，而你没法事先知道该给哪种。最后，按单个请求区分原因（“为什么”）几乎不可能，对服务商尤其如此。
donavanm查看英文原文
I'm a principal at AWS and spent years dealing with this on CloudFront and Route 53. A lot right, and a little off, in the post. Yes, we should definitely communicate to the viewer what's happened and appropriate next steps if any. But there are a handful of challenges that Ive not seen reasonably solved. The first problem is that different viewers need different context, which is especially true for service providers like CDNs. Telling an end user "the page is taking too long" makes sense. But what if its the CDN customer (developer), theyre going to need request IDs and other diagnostics just like Fastly did display. Playing the "we need the RID from the headers you didnt know about to capture" game is a losing proposition. The post and it'd "good" examples suggest a way to contact support, but there is ~0% chance support can help without additional information that isnt included. Expanding on that the post is making really dangerous assumptions and carrying those through to the semantics of the text. Exposing authnz failures as Access Denied vs Not Found is problematic in its own right. Going further to tell the user "You need to login first" is asking for pain in the other 10% of cases where it's a credential or authz problem. Again, different users need different context. And there's no way to know what context to provide apriori. Lastly it's somewhere between incredibly hard to impossible to distinguish the cause ("why") on a per request basis. Especially for service providers like CDNs. The CDN has a cache miss, but can't retrieve the content. Is it a 504 Gateway Timeout because the origin is not responding, 502 Bad Gateway because the origin TLS is broken, 502 because the local clock is off, or a 503 Service Unavailable because of an internal service timeout? Even if you can distinguish what does the CDN represent to the end user; a general fault in the CDN? A specific failure of the origin? Or a simplistic "unavailable." Again, different viewers need different context and semantics. Which you're not going to do at thousands or millions or tps.
默认错误信息应保守，只给一个能回溯日志的标识符。
那条特定的错误信息是我 15 年前在 Varnish Cache 里写的。Max 关于错误信息有很多好观点，但全都需要访问带外信息。我们 Varnish Cache 项目拿不到这些信息：我们不知道谁在运行这个实例、它给什么样的客户端提供什么样的内容。所以默认的 503 信息只暴露一个“XID”随机串，让这个缓存实例的管理员去日志里查全部细节。想展示别的内容的 Varnish 用户可以在 VCL 里自定义，我确信 Fastly 平时也是这么做的。但当一切都不灵的时候——这里显然就是这种情况——Varnish Cache 选择保守。
phkamp查看英文原文
I created that particular error-message in varnish cache 15 years ago. Max has many good points about error messages in general, but all of them require access to out of band information. We in the Varnish Cache Project do not have access to that information, we dont know who runs the varnish instance or what kind of information they serve to what kind of clients. This is why the default '503 message only exposes the "XID" nonce: That allows the administrator of this cache instance to find all the details in the log files. Varnish Cache users who want to present something else can do that from VCL, and I'm pretty sure Fastly normally does. But when all else fails, and here it must have, Varnish Cache errs on the side of caution.
别在用户可见的报错里放玩笑和内部梗，它会流到意想不到的读者面前。
我遇到过不止一个实习生或年轻工程师，得教他们克制住往项目文档、注释或报错里塞俏皮话和玩笑的冲动，尤其是错误信息或任何可能暴露给用户/客户的内容。即使你以为是只有开发团队才会看到的错误，你也不知道它会不会流到你没预料到的读者面前。我有点怀疑，真遇到这条错误信息的人，看到那个致敬老 Amiga OS 错误的梗时有没有被逗乐。
hvocode查看英文原文
I've had more than one intern or young engineer that I've had to teach to resist the urge to put witty comments and jokes in project docs, comments, or errors. Especially in error messages or things that can be exposed to users/customers. Even if it's an error you think only the dev team will see, you never know if it will make its way out to audiences you didn't intend. Somehow I doubt people faced with this error message really were amused by the reference to the old Amiga OS errors....
同类还值得读
编写更好文档的框架
A Framework for Writing Better Documentation
这是 Divio 的文档写作框架，把技术文档按「读者的目标」分成四类：教程（学习导向）、操作指南（问题导向）、参考（信息导向）、解释（理解导向）。
技术写作与文档2021 · 637 分 · 76 评4 条写作要点编辑精选写好一份设计文档
Writing a good design document
这篇 HN 帖子标题为《Writing a good design document》，主题是如何写好一份设计文档；对写作者来说，它值得作为技术写作和结构化说明文的参照。
技术写作与文档2025 · 581 分 · 147 评3 条写作要点编辑精选技术写作课程
Technical Writing Courses
这是 Google 官方免费技术写作课程（两门），讲受众定义、主动语态、短句、文档结构等基础方法。
技术写作与文档2020 · 571 分 · 73 评4 条写作要点编辑精选写出更好的错误信息
Write better error messages
这篇帖子讨论如何写出更好的错误信息，评论补充了开发者场景下的具体做法和真实反面案例。
技术写作与文档2022 · 566 分 · 253 评4 条写作要点编辑精选写一本技术书的经济账
The Economics of Writing a Technical Book
一位技术书作者拆解写书的真实经济账：版税收入往往远低于投入的时间成本。
技术写作与文档2018 · 519 分 · 149 评4 条写作要点编辑精选