技术英语 / 系统课时
区分 warning、note 和 error
区分 warning、note 和 error
英文技术文档中的提示语气不只是排版差异,它决定读者如何判断严重程度和下一步动作。本节用风险、状态与行动三个维度区分 warning、note 和 error,并给出可直接套用的英文写法,避免把普通补充写成警告,也避免把失败写成模糊提醒。
学习目标
- 根据风险和执行状态选择 warning、note 或 error。
- 写出能说明后果、条件和读者动作的提示句。
- 识别三类提示最常见的误用边界。
先看读者是否需要行动
选择提示类型时,先不要从语气强弱出发,而要回答三个问题:事情是否已经失败、继续操作是否可能造成损失、读者现在是否必须采取行动。这样能把提示类型和真实后果绑定,而不是凭感觉选择更“醒目”的词。
| 类型 | 典型含义 | 读者动作 |
|---|---|---|
| note | 补充条件、范围、例外或有用信息 | 通常不需要立即行动 |
| warning | 继续操作可能导致数据丢失、安全风险或难以恢复的结果 | 操作前应停下并确认 |
| error | 某个操作已经失败,系统无法完成预期结果 | 需要定位原因并修复 |
例如,Note: This setting only affects new projects. 只是限定生效范围;Warning: Deleting the key immediately revokes access. 表示继续操作会产生高成本后果;Error: The deployment failed because the image tag does not exist. 则描述已经发生的失败。
把提示写成“事实加动作”
高质量提示不靠 important、critical、serious 这类形容词堆强度,而是明确写出条件、后果和动作。读者应当能在一两句内知道“发生什么”和“我该做什么”。
note 适合补充事实,不必强迫读者执行动作。例如:Note: Changes apply only after you restart the service. 这里的重点是生效条件。
warning 应说明风险,并在可能时给出预防动作。例如:Warning: Rotating this key invalidates all existing tokens. Update dependent services before continuing. 读者能同时看到后果和操作顺序。
error 应描述失败对象,并把修复入口放在附近。例如:Error: The upload failed because the file exceeds 10 MB. Reduce the file size and try again. 与只写 Upload error 相比,这种写法能直接进入修复。
避免把三类信息混在一起
最常见的问题是“严重程度”和“当前状态”混写。warning 通常描述尚可避免的风险,error 通常描述已经发生的失败;如果失败同时带来高风险,可以先报告 error,再在修复步骤前单独加入 warning,不必把两个标签塞进同一句话。
另一个误区是把所有有用信息都写成 note。提示框过多会让页面失去层级,真正重要的信息反而难以检索。普通说明能自然放进正文时,就不需要 note。
不同产品可能有固定的严重度模型,例如日志级别或设计系统中的 info、warning、error。这时应优先遵循产品已有定义,并保持全站一致。写作时真正需要稳定的是判断依据:补充信息用 note,操作前风险用 warning,已经失败的状态用 error。