技术写作与文档2022wix-ux.com编辑精选
写出更好的错误信息
Write better error messages
导读
这篇帖子讨论如何写出更好的错误信息，评论补充了开发者场景下的具体做法和真实反面案例。值得写作者读，因为错误信息本质上也是面向读者的说明文字：要具体、可搜索、带上下文，而不是笼统地说“出错了”。
可以直接用的写作要点
- 01
错误信息要说明程序在做什么、涉及哪个文件/用户/对象，必要时附上源码位置和上下文，让读者能据此定位问题。
- 02
尽量避免“Oops! Something went wrong”这类笼统文案；用户会照读报错来求助，模糊信息会让用户和支持人员都无从下手。
- 03
给错误信息加唯一、可搜索的错误码，既方便用户自行搜索解决，也方便团队监控异常激增。
- 04
设计错误文案不能只考虑正常路径，要提前覆盖边界情况，并让写好错误信息、减少错误本身成为被认可的工作。
HN 评论精选
给错误加唯一可搜索的错误码，并监控它的出现量，既帮用户自助也帮团队发现回归。
我同意文中所有观点，但漏了很重要的一点：尽可能给每个错误加上应用级或全局唯一的错误码，例如 YCOM-HN-9021。给出一个明确可谷歌搜索的字符串，能帮用户自行解决问题，也可以对这个字符串设置谷歌快讯——如果你花三个月开发的新功能上线一周后，谷歌提示 YCOM-HN-9021 出现量涨了 9000%，那多半是哪里坏了。另外要尽可能开放客户沟通渠道，但多数用户不会主动联系客服：现代用户对客服信任度很低（而且说实话，找客服常常更麻烦），他们更可能去 Reddit 或技术论坛找答案。能追踪到这些用户是非常有利的。
munk-a查看英文原文
I don't disagree with any points but they missed a big one. If at all possible, include some application (or attempt at a globally) unique error code on each of your errors - i.e. YCOM-HN-9021. When you provide a clearly googleable string you can help your users independently resolve the issue and you can also set up google alerts on the string - if you roll out a new feature that took 3 months to develop and a week later google tells you that YCOM-HN-9021 is up 9000% you probably broke something. If at all possible make yourself open to client communication but most users won't reach out about an error - users have very low trust in customer care in the modern world (and it is, honestly, often more trouble than it's worth) and are more likely to turn to reddit/technical forums for a solution. It is extremely advantageous to try and track these users.
开发者错误信息要包含动作、对象、位置和上下文，并保持可搜索，不能只给一个泛化短语。
我再补充几条面向开发者的错误信息写法：说明程序当时想做什么；让信息唯一且可搜索；信息要详细；务必带上文件名或程序处理困难的对象；如果可能，包含源码位置；如果可能，包含有用的上下文；给字符串加引号——偶尔会有意外空白混进去，不加引号很难查。例如不要只报“Open failed: NOT_FOUND”，而应报“job.c:2105 Failed to open job description file '/var/spool/jobs/125.json' when processing job #5 for user 'alice': NOT_FOUND”。这样我就不用 strace 去猜它在找什么，也知道是哪个用户，不必翻数据库找哪条记录可能有问题。另外，没有上下文的通用错误信息很糟糕，代码库一大，常见关键词根本搜不到。可谷歌的错误码很好，但不应替代错误信息本身。理想情况是搜源码就能立刻找到这条信息来自哪里。
dale_glass查看英文原文
I'll add a few for developer-oriented messages. * Say what the program was trying to do. * Make the message unique and searchable. * Make it detailed. * FFS, include the filename or whatever else the program is having trouble with. * If possible, include the source code location. * If possible, include useful contextual information. * Quote strings. Once in a while, some unexpected whitespace sneaks in somewhere and this can be hard to figure out. Eg, don't just abort with "Open failed: NOT_FOUND". Abort with "job.c:2105 Failed to open job description file '/var/spool/jobs/125.json' when processing job #5 for user 'alice': NOT_FOUND". This way I don't have to strace the damn thing to try and figure out what's it looking for, and know which user it was for, so I don't have to dig around and try and figure out which entry in the database might contain the wrong information. Also, context-free, generic error messages are awful. A large enough codebase may be impossible to search for some very common keywords. If possible, googleable error codes are great to have, but they shouldn't replace the error message. It's ideal if you can search the source code and instantly find where the error message originates.
模糊的“Oops”式报错让支持人员无法定位问题，而用户其实会反馈所见信息来帮助排查。
上一份工作中，写明确无歧义的错误信息是不被鼓励的，所有报错都只能是“Oops! Something went wrong”。理由是“反正我们告诉用户信息，他们也做不了什么”，尽管我们收到大量帮助台工单，都是“Oops!”出现在无数不同场景里，我们根本没法判断实际是哪个错误触发了这条消息。用户自然会报告他们看到的错误信息，因为他们是在帮我们看到问题。我不明白这么简单的道理为什么很难理解。
Minor49er查看英文原文
At a previous job, writing unambiguous error messages was discouraged. Everything just had to be "Oops! Something went wrong" The reasoning was that "users can't do anything with information we tell them anyways", despite the overwhelming number of help desk tickets we'd get from "Oops!" appearing in a million different scenarios with no clear way for us to tell what error actually caused the message to appear. Users naturally report the messages that they see because they're helping us to see the problem. I didn't get why that was such a hard concept to understand
糟糕错误信息往往源于激励制度和设计流程只关注正常路径，边界情况被丢给赶工期的开发者。
20 年前我在 Adobe 做 Acrobat，主要算“Windows 那边的人”，但也负责 Mac 上的开发和测试。我在 Mac 上安装 Acrobat 时收到一条信息：“你的硬盘太小了”。我的什么太小？！后来在 Windows 上又遇到一个意外弹窗：“你不在这里”。什么鬼？我搜代码找到这个字符串，它来自一个叫 CantHappen() 的函数。这个函数在很多程序员认为“不可能走到这里”的地方被调用。但 CantHappen() 当然还是发生了。翻代码时我发现许多其他奇怪、难以理解、有时甚至冒犯人的信息。于是我启动了一个项目，逐一清理我们的信息，让它们更清晰、更有信息量，甚至更好的是，在可能时干脆不显示信息，而是直接处理好情况。这些糟糕信息的根因有两方面：第一，程序员不会因为写好错误信息或想办法避免错误而加薪，我们只按完成了多少工作来评价；第二，我们确实有产品设计师负责指定所有面向用户的信息，但设计师主要考虑“正常路径”，没想到边界情况，那些就留给时间压力下的开发者处理。
Stratoscope查看英文原文
20 years ago I was working on Acrobat at Adobe. I was mostly the "Windows guy" but also worked and tested on the Mac. When I tried to install Acrobat on my Mac, I got this message: "Your hard disk is too small" My what is too small?! Later, on Windows I got this unexpected popup: "You are not here" WTF? I searched the code for that string and found it in a function named "CantHappen()". This function was called in numerous places where the programmer thought there was no possible way for the code to get to that place. But of course CantHappen() did happen. As I looked through the code I found many other messages that were bizarre and incomprehensible and sometimes downright offensive. So I started a project to go through all our messages and make them more clear and informative - and even better, when possible to not have the message at all but just take care of the situation. The underlying cause of these bad messages was twofold: 1. Programmers never got raises for writing great error messages or finding ways to avoid them in the first place. We were just rated on how much work we got done. 2. We did have a product designer who was supposed to specify all user-facing messages. But the designer mainly considered the "happy path" and didn't think about edge cases. It was left to developers working under time pressure to handle those.
同类还值得读
编写更好文档的框架
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 条写作要点编辑精选写一本技术书的经济账
The Economics of Writing a Technical Book
一位技术书作者拆解写书的真实经济账：版税收入往往远低于投入的时间成本。
技术写作与文档2018 · 519 分 · 149 评4 条写作要点编辑精选Diátaxis——技术文档编写的系统化方法
Diátaxis – A systematic approach to technical documentation authoring
Diátaxis 是一套把技术文档按「教程、操作指南、参考、解释」四类拆分的写作框架，核心是让每一篇文档只服务一种读者需求、只承担一种写作任务。
技术写作与文档2024 · 514 分 · 113 评4 条写作要点编辑精选