技术英语 / 系统课时

做一次技术与语言双重审校

做一次技术与语言双重审校

文档写完并不等于可以发布。真正的审校需要同时回答两类问题:内容在技术上是否正确,以及读者能否用自然、明确的英文理解并执行。下面建立一套可重复的双重审校顺序,并把示例、术语和链接都纳入检查范围。

学习目标

  • 按技术正确性和语言质量两个维度审查英文技术文档
  • 验证术语、代码示例和链接,而不是只检查拼写与语法
  • 用分轮审校减少遗漏,并判断修改后是否需要重新验证

先把技术事实审对

第一轮只关注“读者照着做会不会得到正确结果”,不要同时纠结句式是否优美。把注意力集中在版本、参数、默认值、前置条件、代码行为和结果描述上,更容易发现真正会误导读者的问题。

技术审校至少检查这些内容:命令和 API 是否真实存在;选项名称与大小写是否正确;步骤顺序是否缺少前置操作;示例输入能否得到文中声称的结果;版本限制是否明确;错误处理是否与实际行为一致。

如果一句话写着“the command always creates a new file”,审校者就应该验证 always 是否真的成立。只要存在覆盖、跳过或报错等分支,就应改成带条件的表述,而不是保留过度绝对的结论。

再检查英文是否准确一致

技术事实稳定后,再进行语言轮。此时重点不是把文字写得华丽,而是减少歧义、统一术语并让动作关系清楚。

同一个概念应固定使用同一个名称。例如前文使用 configuration file,后文不要无理由切换成 config document。按钮名、命令、字段和类型应按照产品或代码中的真实拼写保留,不为了语言自然度擅自改写标识符。

审校句子时,可以依次检查主语是否明确、动词是否直接、条件是否靠近对应动作、代词是否有唯一指向。技术步骤通常优先使用简洁主动句,例如 “Run the command to generate the report.” 比绕行的被动结构更容易执行。

检查对象 需要回答的问题
事实 版本、默认值、参数和行为是否可验证
术语 同一概念是否始终使用同一名称
句子 谁执行什么动作、在什么条件下执行是否清楚
示例 示例是否能解析、编译或运行,并得到相符结果
链接 目标是否存在,链接文字是否说明目标内容

验证示例而不是目测代码

代码看起来正确并不代表它能执行。能够自动验证的示例,应尽量交给解析器、编译器或测试程序。下面的命令会读取 README.md 中所有标记为 Python 的围栏代码,并逐段进行语法编译检查;它不会执行示例,因此适合先发现缩进、括号和语法错误。

bash
python - <<'PY'
from pathlib import Path
import re

text = Path("README.md").read_text(encoding="utf-8")
blocks = re.findall(r"`python
(.*?)
`", text, flags=re.S)

for index, source in enumerate(blocks, start=1):
    # 先做语法验证;需要验证运行结果时还应增加项目测试。
    compile(source, f"<README-python-{index}>", "exec")

print(f"validated {len(blocks)} Python example(s)")
PY

预期输出

text
validated <N> Python example(s)

<N> 是文档中 Python 示例的实际数量,具体值可能不同。如果命令抛出 SyntaxError,应先修复对应代码块,再继续语言审校。对于依赖网络、数据库或特定运行环境的示例,还需要在匹配的测试环境中执行,而不能把语法通过当作行为正确。

把链接和改动后的内容重新走查

链接审校不能只看 Markdown 语法是否完整。外部链接需要确认仍然可访问,并优先链接到稳定的官方页面;内部链接还要检查文件移动后相对路径和锚点是否仍然有效。链接文字应描述目标,例如 “See the authentication guide”,而不是大量使用含义不明的 “click here”。

一次修改可能破坏已经通过检查的内容。比如为了统一术语重写句子时,可能误改命令名;调整代码示例后,原来的结果说明也可能失效。因此最后应对所有实质性修改执行一次回归检查:事实改动重新验证事实,代码改动重新运行示例,标题改动重新检查内部锚点。

双重审校的关键不是把技术检查和语言检查机械地各做一次,而是让每个可验证声明都有依据,让每个关键术语只有一种稳定表达。完成这两轮后,文档才同时具备“做得对”和“读得懂”这两个发布条件。

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

目录与阅读设置

阅读设置

17

记录一个想法

做一次技术与语言双重审校

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

登录哪都通