优质文档 - 一位翻译者的视角

简介

译者对编写清晰、简洁的文档有宝贵的见解。他们比大多数人更了解什么内容不易翻译，什么内容会令读者感到困惑。本文将探讨其中一些问题，并强调文档创建的最佳实践。

作者视角

软件文档有助于用户了解如何有效使用特定软件。他们需要了解最终会获得什么，以及会带来哪些好处。同时，当您创建文档时，这意味着您创建的文档不仅是给自己看的，也是为您的同事以及其他可能阅读它的人看的。其他人可能不是来自英语国家。这意味着英语不是他们的母语。因此，请遵循以下基本规则，使您的文档对所有用户都更具可读性。

使用通俗易懂的语言

您不知道您的用户是谁。这位用户是否熟悉该领域，他们是技术娴熟的开发者还是初学者。通俗易懂的语言是指清晰、简洁且易于目标受众第一次阅读时理解的沟通方式。它避免使用行话、技术术语和复杂的句子结构，而是采用更简单的语言和清晰的组织。目标是确保信息能够被广大受众理解和接受，无论其背景或阅读水平如何。通常，您可以通过将句子结构或命令简化为其最基本的形式来实现这一点。

避免使用习语、行话、首字母缩略词和缩略语

对于不熟悉习语、行话、缩略语和首字母缩略词的读者来说，这些内容可能会造成混淆，特别是对于非母语人士、新员工或您特定领域之外的人员。

习语通常具有文化特异性，对于国际读者来说可能很难理解。
行话涉及只有该领域的专家才可能认识的专业术语。
缩略语虽然可以缩短英语中的单词，但并非所有语言都存在，这会使翻译变得困难。
首字母缩略词可能会引起歧义，特别是当首次使用时未进行定义。

示例

❌ “一旦你掌握了仪表板的使用方法，剩下的就易如反掌了。” 在这里，作者同时使用了缩略语、俚语和习语。

✅ “一旦你学会了如何使用仪表板，剩下的就很简单了。” 通过用与每个词相关的词替换缩略语、俚语和习语，含义变得清晰。

比喻性语言，如习语，通常不易翻译。技术撰稿人或译者可能很难用其他语言传达相同的含义。

示例

❌ “下周我们再聊聊遗留的工单。”

✅ “下周我们开会，审查未解决的支持请求。”

即使在同一组织内，如果行话和首字母缩略词的含义不被普遍知晓，也可能令人困惑。

示例

❌ “将 CSV 上传到 CMS，并根据 SOP 进行标记。”

✅ “将 CSV（逗号分隔值文件）上传到内容管理系统，并根据标准操作程序进行标记。”

注意：如果要使用首字母缩略词，请始终在首次使用时定义它们：“客户关系管理 (CRM) 系统”。

通过消除习语和不必要的行话，文档的含义会更加清晰。用它们所代表的词替换缩略语，意味着所有语言的翻译工作都将更容易。当您替换或定义首字母缩略词时，您的文档对读者来说是最容易理解的。

使用主动语态

主动语态强调动作的执行者，从而清楚地表明谁或什么对动词的动作负责。

示例

系统会打开对话框，您需要在其中填写表单。

请避免使用复杂的表单，因为它可能会让读者感到困惑。

有关主动语态的使用及其重要性的更多信息，请参阅本文观点和此外部来源。

具体步骤

如果文档中有具体步骤，请将它们分开。

例如

步骤 1 - 转到该部分
步骤 2 - 单击按钮
步骤 3 - 填写表单
...
步骤 N - 保存更改

必要时使用截图

在需要的地方使用正确的截图。这意味着您不需要到处添加截图，只需在需要进一步解释的地方添加。

使用示例

如果您需要填写表单，请提供用户如何填写该表单的示例。如果有限制，请提及。

结论

编写优秀的文档不仅是使其在技术上准确，而且对其是否能让读者立即理解也至关重要。当技术文档需要翻译成其他语言时，这一点尤为重要。在本文中，作者的意图是强调编写优秀、清晰的文档的具体技巧。

作者：Ganna Zhyrnova

贡献者：Steven Spencer