write-better-error-messages

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Write Better Error Messages

编写更好的错误消息

Use this skill to make error messages specific, calm, accountable, and useful.

使用此 Skill，让错误消息具体、冷静、有担当且有用。

Attribution

来源说明

This skill is adapted from Jenni Nadler's Wix UX article "When life gives you lemons, write better error messages", published by Wix UX. It incorporates the article's guidance and the lessons shown in its annotated screenshots: the bad-message modal, the improved-message modal, the generic-vs-unclear comparison, and the error-inventory board.

此 Skill 改编自 Jenni Nadler 的 Wix UX 文章“当生活给你柠檬时，写出更好的错误消息”，由 Wix UX 发布。它融合了文章中的指导原则，以及其带注释截图中展示的经验：糟糕消息弹窗、改进后的消息弹窗、通用消息与含糊消息对比，以及错误消息清单看板。

Core Test

核心检查

Before writing or approving an error message, answer:

What happened?
Why did it happen, at the most useful level of detail the product can honestly provide?
What was not affected, if anything needs reassurance?
What can the user do now?
What can they do if that does not work?

If the product cannot answer these questions, treat it as a product or engineering gap, not only a copy problem.

在编写或批准错误消息前，请回答：

发生了什么？
为什么发生？在产品能够诚实提供的最有用细节层级上说明原因。
哪些内容未受影响？如果需要安抚用户，请说明。
用户现在能做什么？
如果上述操作无效，用户还能做什么？

如果产品无法回答这些问题，应将其视为产品或工程方面的缺口，而不只是文案问题。

Avoid

应避免

Do not use cutesy or casual tone when the stakes are high. Avoid "Oops", "Whoops", "Uh oh", "Yikes", and jokes for flows involving money, publishing, work continuity, account access, data, or user trust.
Do not blame the user. Focus on the problem and the recovery path.
Do not blame third parties when the user is operating inside your product. Prefer "We're having trouble connecting to [service]" over "[service] is not responding."
Do not expose implementation details unless they help the user act. Replace terms like "fetch", "credentials denied", "500", or "unknown exception" with the outcome and next step.
Do not ship "Something went wrong" when the system knows more. A generic fallback is acceptable only when no specific diagnosis is available, and even then it should include a next step or escape route.
Do not confuse "specific" with "clear." A message can mention permissions, tokens, scopes, or settings and still be unclear if the user cannot tell what to do.

当 stakes 较高时，不要使用卖萌或过于随意的语气。对于涉及资金、发布、工作连续性、账户访问、数据或用户信任的流程，应避免使用“糟糕”“哎呀”“呜呼”“妈呀”和讲笑话等表达。
不要责怪用户。应聚焦于问题和恢复路径。
当用户正在你的产品中进行操作时，不要责怪第三方。优先使用“我们连接 [服务] 时遇到了一些问题”，而不是“[服务]没有响应”。
除非实现细节有助于用户采取行动，否则不要暴露这些细节。将“fetch”“credentials denied”“500”或“unknown exception”等术语替换为具体结果和后续操作。
当系统掌握了更多信息时，不要上线“出了点问题”这类消息。只有在无法获得具体诊断时，才可以使用通用兜底消息；即便如此，也应包含后续操作或退出路径。
不要混淆“具体”和“清晰”。一条消息即使提到 permissions、tokens、scopes 或 settings，如果用户仍不知道该做什么，就依然不够清晰。

Prefer

Rewrite Workflow

重写工作流

Identify the context and stakes: user goal, surface, data at risk, whether the user can recover, and whether the error blocks the flow.
Map the cause with engineering/product if needed: trigger, frequency, known causes, affected state, and realistic fixes.
Classify the current message:
- Generic: hides available information, such as "Something went wrong and this action could not be completed."
- Unclear: tries to explain but leaves the user unsure what to do, such as "Make sure you allow the requested permissions and try again."
- Jargon-heavy: names internal mechanics rather than user-visible outcomes.
- Blaming: points at the user or an integration instead of owning the experience.
- Tone mismatch: too cute, dramatic, or casual for the stakes.
Draft using this shape:
- Title: user-visible outcome.
- Body: concise cause plus reassurance, if relevant.
- Action: primary recovery step.
- Escape: support/help path if retrying may fail.
Remove any sentence that does not help the user understand, recover, or trust the product.
Verify the final copy against the Core Test.

识别上下文和 stakes：用户目标、界面载体、存在风险的数据、用户能否恢复，以及错误是否阻塞了流程。
如有需要，与工程或产品团队共同梳理原因：触发条件、发生频率、已知原因、受影响状态和可行的修复方案。
对当前消息进行分类：
- 通用：隐藏了已有信息，例如“出了点问题，无法完成此操作。”
- 含糊：试图进行解释，但用户仍不知道该做什么，例如“请确保允许所请求的权限，然后重试。”
- 术语密集：提及内部机制，而不是用户可见的结果。
- 归咎用户：将问题指向用户或集成服务，而不是主动承担体验责任。
- 语气不匹配：对于当前 stakes 而言，内容过于卖萌、夸张或随意。
按照以下结构起草：
- 标题：用户可见的结果。
- 正文：简洁说明原因，并在相关时提供安抚信息。
- 操作：主要的恢复步骤。
- 备用路径：如果重试失败，提供支持或帮助入口。
删除所有无助于用户理解、恢复操作或信任产品的句子。
使用核心检查验证最终文案。

Screenshot-Derived Patterns

从截图总结的模式

Use these patterns from the article's screenshots when reviewing UI copy:

Bad annotated modal: "Whoops! Something went wrong" plus a third-party blame statement, technical wording about fetching data, and "Try again later." Diagnose this as tone mismatch, blame shifting, jargon, and a too-generic next step.
Good annotated modal: "Unable to connect your account" plus "Your changes were saved", an honest cause on the product side, "Please try connecting again", and a Customer Care fallback. Use this as the target structure: outcome, reassurance, cause, next step, escape route.
Generic vs unclear comparison: "Something went wrong..." is generic because it says almost nothing; "Make sure you allow the requested permissions..." is unclear because it uses confusing language without telling users where or how to act. Fix both with specific context and an actionable recovery path.
Inventory screenshot: a board or spreadsheet should track message, trigger, owner, priority, error type, frequency, blocked flow, due date, status, and final copy. Error cleanup is cross-functional work, not only UX writing.

评审 UI 文案时，可使用文章截图中的以下模式：

糟糕的带注释弹窗：“哎哟！出了点问题”，再加上归咎第三方的表述、有关获取数据的技术措辞，以及“稍后再试”。应将其诊断为语气不匹配、转移责任、使用技术术语，以及后续操作过于笼统。
良好的带注释弹窗：“无法连接您的账户”，加上“您的更改已保存”、产品端的诚实原因、“请尝试重新连接”，以及 Customer Care 备用路径。将其视为目标结构：结果、安抚信息、原因、后续操作和退出路径。
通用与含糊消息对比：“出了点问题……”属于通用消息，因为它几乎什么都没说；“请确保允许所请求的权限……”属于含糊消息，因为它使用了令人困惑的语言，却没有告诉用户应在何处或如何采取行动。应以具体上下文和可执行的恢复路径改进这两类消息。
清单截图：看板或电子表格应跟踪消息、触发条件、负责人、优先级、错误类型、频率、阻塞流程、截止日期、状态和最终文案。错误清理是跨职能工作，不只是 UX 写作。

Inventory And Review

清单与评审

For a batch of errors, create or update a small inventory:

Field	Purpose
Current message	The exact user-facing copy.
Trigger	What condition shows it.
Cause known?	Whether engineering can identify the reason.
Frequency	How often users hit it.
Blocking?	Whether it prevents task completion.
Affected state	What changed, failed, or was preserved.
Owner	Product, engineering, design, or writing owner.
Proposed copy	Revised title/body/actions.
Follow-up	Instrumentation, design change, support link, or backend fix.

Prioritize errors that happen often or block users from completing important flows. Revisit launched errors after real usage data is available, especially for new products that shipped with broad fallback messages.

对于一批错误消息，请创建或更新一份小型清单：

字段	用途
当前消息	用户看到的完整文案。
触发条件	出现该消息的情况。
是否已知原因	工程团队能否识别具体原因。
发生频率	用户遇到该问题的频率。
是否阻塞	该问题是否阻止用户完成任务。
受影响状态	哪些内容发生了变化、失败或被保留。
负责人	产品、工程、设计或写作负责人。
建议文案	修改后的标题、正文和操作。
后续事项	Instrumentation、设计变更、支持链接或后端修复。

应优先处理经常发生或会阻止用户完成重要流程的错误。在获得真实使用数据后，应重新审视已上线的错误，尤其是那些仅使用宽泛兜底消息的新产品。

Output Format

输出格式

When rewriting for the user, prefer:

markdown

Current: "..."
Issue: Generic / unclear / jargon / blame / tone mismatch / missing next step
Rewrite:
Title: ...
Body: ...
Primary action: ...
Fallback: ...
Reasoning: ...

Keep the reasoning short and grounded in what changed for the user.

为用户重写文案时，优先使用：