技术英语 / 系统课时

先整理原始中文技术资料

先整理原始中文技术资料

英文技术文档的质量通常取决于翻译前的材料是否清楚。本节把接口说明、代码注释和设计笔记先整理成可验证的事实、步骤、限制与示例,避免把含糊中文直接翻成更难发现问题的英文。

学习目标

  • 从不同来源中区分事实、操作步骤、限制条件和示例
  • 删除猜测、重复信息和无法验证的表述
  • 形成可直接用于英文写作的中文事实清单

先把来源拆开处理

不要一开始就把所有材料拼成一篇文章。接口说明更适合确认输入输出和错误条件,代码注释适合补充实现约束,设计笔记则常包含背景、取舍和尚未落地的设想。来源不同,可信度和用途也不同。

整理时先给每条信息标出来源,再判断它属于“已实现事实”还是“计划、推测、讨论”。只有可以从代码、接口行为、测试结果或明确决策中验证的内容,才能直接进入发布文档。

把信息归入四类

最实用的整理方式是把材料归入事实、步骤、限制和示例四类。事实回答“系统现在是什么样”,步骤回答“读者要按什么顺序做”,限制说明“什么情况下不成立”,示例则提供一个可复现的具体用法。

下面是片段示例,假设这些内容来自同一个内部功能的接口说明、代码注释和设计笔记,目的是练习识别信息角色,不要求独立运行。

text
接口说明:POST /v1/jobs 创建任务,成功返回 202。
代码注释:同一 clientId 最多允许 3 个运行中任务。
设计笔记:以后考虑把并发数做成租户级配置。
测试记录:缺少 clientId 时返回 400。

可以整理成:

  • 事实:POST /v1/jobs 用于创建任务;成功状态码为 202
  • 限制:同一 clientId 最多同时有 3 个运行中任务
  • 错误条件:缺少 clientId 时返回 400
  • 不进入当前文档:并发数改为租户级配置,因为它仍是未来设想

这种分类比直接改写句子更重要,因为它先解决“该不该写”和“写成什么角色”,再解决英文措辞。

把含糊表述改成可验证事实

中文内部资料常出现“尽量”“通常”“必要时”“很快”等词。它们如果没有条件或数据支撑,不适合直接翻译。应先追问触发条件、范围、默认值或可观察结果。

例如,“系统会自动重试”至少还缺重试对象、次数和触发条件。若代码确认只有网络超时会重试两次,就应先整理为“请求发生网络超时时,客户端最多额外重试两次”。后续英文写作才有稳定事实可依赖。

形成写作清单

正式起草英文前,给每个读者任务保留一份最小清单:目标、前置条件、步骤、成功结果、失败条件和限制。没有内容的项可以省略,不要为了格式完整而补空话。

最后再做一次交叉检查:接口行为与代码是否一致,示例是否满足当前限制,设计笔记中的计划是否误混进现状。完成这一步后,英文写作就不再是“边翻译边猜”,而是把已经确认的技术事实组织成读者能执行的说明。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

先整理原始中文技术资料

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通