用户首次接触应用程序的文档，通常不是用户手册或在线帮助。通常，第一次接触文档是错误消息。
技术文档撰写人员应该参与编写错误消息。这是工作中重要但经常被忽视的一部分。毕竟，错误消息也是文档，尽管是嵌入在代码中的文档。
您可能会问，为什么技术文档撰写人员应该参与创建错误消息？许多错误消息在帮助用户方面做得不好。事实上，它们读起来常常像是机器为机器编写的。您有多少次遇到过类似“发生意外错误”或（我最喜欢的）“对象引用未设置为对象的实例？”之类的错误消息？像我一样，当您看到这样的错误消息时，您可能会挠头。
但是，编写错误消息并不像听起来那么简单。我想分享一种我多年来使用和改进的技术，以编写有效的错误消息。
优秀错误消息的要素
错误消息应该是有意义的。我的意思是，不仅对开发人员，而且对软件用户也充满意义。为了防止任何恐慌或困惑，消息应该清晰。
有意义的错误消息应该- 简短（您可以用句子片段编写）；
- 包含对错误原因的简单语言描述；以及
- 使用措辞或语气，不（明确或不明确地）责备用户。
消息还可以包含错误代码或日志或错误文件的位置，用户可以将其发送给支持人员。您还可以包含指向文档或任何故障排除信息的链接。
假设您正在为打印文档失败编写错误消息。“打印失败”消息不如它可能的那样有意义。相反，该错误消息可以读作
- “我无法打印您的文档。请检查您的打印机或连接。”
- “打印失败。请检查您的打印机。”
- “无法打印您的文件。请检查您的打印机或参阅故障排除文档。”
- “文件未打印。您的打印机是否已打开？”
创建有效的错误消息
我向同事们传授了我编写更好错误消息的技术，他们发现它很有用。我想您也会觉得有用。
如果您需要重写现有的错误消息，请将当前文本写在便利贴上，并将其贴在显示器的右上角。或者，如果您正在编写新消息，请与开发人员或质量保证人员交谈，以了解有关错误详情。将要点写在便利贴上，然后将其贴在显示器上。无论哪种方式，便利贴都在那里作为提示。
接下来，启动文本编辑器或拿起笔和纸开始写作。目标是让想法和文字从您的大脑中流出。不要担心您写的东西是否好。为什么？大多数写出来的东西都不会很好。大多数都将无法使用。您可以稍后消除糟粕。尝试为消息提出 4 到 10 个变体；越多越好。
始终以对话式语气编写错误消息，但不要过于可爱或开玩笑。虽然像“哎呀！您的打印机和我之间出现了一些问题。最好检查一下一切是否正常”这样的错误消息很容易阅读，但它太长，并且没有足够快地切入正题。修剪，修剪，修剪
获得列表后，将其缩减为两到五个可能性。然后，将这些可能性发送给您的团队。这通常会导致对一段文本达成共识。通常，但并非总是如此。如果未达成共识，请尝试混合使用几个最受欢迎的选择以获得可接受的替代方案。
使用此技术的关键是不必纠结于所有想法的质量。您只需要让文字流动，然后编辑和调整最终的错误消息，直到它足够好用为止。
8 条评论