write-better-error-messages

编写更好的错误消息

使用此技能，让错误消息具体、冷静、负责且实用。

署名

此技能改编自 Jenni Nadler 为 Wix UX 撰写的文章 "When life gives you lemons, write better error messages"，由 Wix UX 发布。内容结合了文章中的指导，以及带注释截图所展示的经验：糟糕的消息弹窗、改进后的消息弹窗、笼统与含糊消息的对比，以及错误盘点看板。

核心检验

编写或审核错误消息前，请回答：

1. 发生了什么？
2. 为什么会发生？请提供产品能够如实说明的最有用的细节。
3. 有哪些内容未受影响（如需安抚用户）？
4. 用户现在可以做什么？
5. 如果这样做没有效果，用户还可以怎么办？

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

应避免

• 事关重大时，不要使用俏皮或随意的语气。涉及金钱、发布、工作连续性、账户访问、数据或用户信任的流程中，避免使用“哎呀”“糟了”“哦不”“天哪”之类的说法或玩笑。
• 不要责怪用户。应聚焦问题和恢复途径。
• 用户在你的产品中操作时，不要责怪第三方。优先使用“我们无法连接到 [service]”，而不是“[service] 没有响应”。
• 除非有助于用户采取行动，否则不要暴露实现细节。将“获取”“凭据遭拒”“500”或“未知异常”等术语替换为实际结果和后续步骤。
• 如果系统掌握更多信息，就不要发布“出了点问题”。只有在无法提供具体诊断时，才可以使用笼统的备用消息；即便如此，也应包含后续步骤或脱困途径。
• 不要混淆“具体”和“清楚”。即使消息提到了权限、令牌、范围或设置，如果用户不知道该怎么做，仍然不够清楚。

建议

• 先说明结果：“我们无法连接你的账户”“图片未上传”或“更改已保存，但邮件未发送。”
• 尽可能解释原因：“因为文件大于 25 MB”“因为你的会话已过期”或“因为我们这边出了问题。”
• 安抚用户，说明已保留的内容：“草稿已保存”“账单设置未更改”或“尚未邀请任何人。”
• 提供明确的下一步：“尝试重新连接”“选择小于 25 MB 的文件”“重新登录”或“检查是否允许弹出窗口。”
• 用户可能受阻时，提供脱困途径：链接到支持渠道、帮助文章，或提供重试、取消、保存草稿、下载数据或联系客户服务的选项。
• 在情况严重或无法恢复时，可少量使用“请”来表达体谅，不要把它当作填充语。

改写流程

1. 明确情境和利害关系：用户目标、界面、面临风险的数据、用户能否恢复，以及错误是否会阻断流程。
2. 必要时与工程或产品团队一起梳理原因：触发条件、发生频率、已知原因、受影响状态和可行的修复方式。
3. 对当前消息分类：
   • 笼统：隐去了已有信息，例如“出了点问题，无法完成此操作。”
   • 含糊：尝试解释，却没有让用户明确知道该怎么做，例如“请确保允许所需权限，然后重试。”
   • 术语堆砌：描述内部机制，而非用户可见的结果。
   • 责怪用户：将责任推给用户或集成服务，而不是由产品承担体验责任。
   • 语气不当：对于事情的严重程度来说，语气过于俏皮、夸张或随意。
4. 按以下结构起草：
   • 标题：用户可见的结果。
   • 正文：简要说明原因，并在适当时安抚用户。
   • 操作：主要恢复步骤。
   • 脱困途径：如果重试可能无效，提供支持或帮助渠道。
5. 删除任何无助于用户理解问题、恢复操作或信任产品的句子。
6. 根据核心检验核对最终文案。

从截图中提炼的模式

审核 UI 文案时，可参考文章截图中的这些模式：

• 带有批注的错误示例弹窗：“哎呀！出了点问题”，加上归咎于第三方的说法、描述数据获取过程的技术术语，以及“请稍后再试”。应诊断为语气不匹配、推卸责任、使用术语，以及下一步指引过于笼统。
• 带有批注的优秀示例弹窗：“无法连接你的账户”，加上“已保存你的更改”、如实说明产品端的原因、“请重新尝试连接”，以及联系客户支持的备用方案。以此为目标结构：结果、安心说明、原因、下一步、备用方案。
• 笼统与不清楚的对比：“出了点问题……”之所以笼统，是因为几乎没有传达任何信息；“请确保允许所请求的权限……”之所以不清楚，是因为措辞令人困惑，却没有告诉用户去哪里或如何操作。两者都应通过提供具体情境和可执行的恢复方案来改进。
• 错误清单截图：看板或电子表格应跟踪消息、触发条件、负责人、优先级、错误类型、频率、受阻流程、截止日期、状态和最终文案。清理错误信息是跨职能工作，不只是 UX 写作的职责。

清单与审核

批量处理错误信息时，创建或更新一份简要清单：

字段	用途
当前消息	面向用户显示的准确文案。
触发条件	显示该消息的条件。
是否已知原因？	工程团队能否识别原因。
频率	用户遇到该问题的频率。
是否阻塞？	是否会阻止用户完成任务。
受影响的状态	发生了哪些变化、失败了什么，或保留了什么。
负责人	产品、工程、设计或文案负责人。
建议文案	修改后的标题、正文和操作项。
后续跟进	埋点、设计更改、支持链接或后端修复。

优先处理频繁发生或会阻止用户完成重要流程的错误。上线后，应在获取真实使用数据后重新检查错误信息；尤其是新产品上线时使用了宽泛的兜底消息，更应如此。

输出格式

为用户改写时，建议采用以下格式：

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

说明应简短，并围绕用户体验发生了什么变化。