技术英语 / 系统课时
做一次技术与语言双重审校
做一次技术与语言双重审校
文档写完并不等于可以发布。真正的审校需要同时回答两类问题:内容在技术上是否正确,以及读者能否用自然、明确的英文理解并执行。下面建立一套可重复的双重审校顺序,并把示例、术语和链接都纳入检查范围。
学习目标
- 按技术正确性和语言质量两个维度审查英文技术文档
- 验证术语、代码示例和链接,而不是只检查拼写与语法
- 用分轮审校减少遗漏,并判断修改后是否需要重新验证
先把技术事实审对
第一轮只关注“读者照着做会不会得到正确结果”,不要同时纠结句式是否优美。把注意力集中在版本、参数、默认值、前置条件、代码行为和结果描述上,更容易发现真正会误导读者的问题。
技术审校至少检查这些内容:命令和 API 是否真实存在;选项名称与大小写是否正确;步骤顺序是否缺少前置操作;示例输入能否得到文中声称的结果;版本限制是否明确;错误处理是否与实际行为一致。
如果一句话写着“the command always creates a new file”,审校者就应该验证 always 是否真的成立。只要存在覆盖、跳过或报错等分支,就应改成带条件的表述,而不是保留过度绝对的结论。
再检查英文是否准确一致
技术事实稳定后,再进行语言轮。此时重点不是把文字写得华丽,而是减少歧义、统一术语并让动作关系清楚。
同一个概念应固定使用同一个名称。例如前文使用 configuration file,后文不要无理由切换成 config document。按钮名、命令、字段和类型应按照产品或代码中的真实拼写保留,不为了语言自然度擅自改写标识符。
审校句子时,可以依次检查主语是否明确、动词是否直接、条件是否靠近对应动作、代词是否有唯一指向。技术步骤通常优先使用简洁主动句,例如 “Run the command to generate the report.” 比绕行的被动结构更容易执行。
| 检查对象 | 需要回答的问题 |
|---|---|
| 事实 | 版本、默认值、参数和行为是否可验证 |
| 术语 | 同一概念是否始终使用同一名称 |
| 句子 | 谁执行什么动作、在什么条件下执行是否清楚 |
| 示例 | 示例是否能解析、编译或运行,并得到相符结果 |
| 链接 | 目标是否存在,链接文字是否说明目标内容 |
验证示例而不是目测代码
代码看起来正确并不代表它能执行。能够自动验证的示例,应尽量交给解析器、编译器或测试程序。下面的命令会读取 README.md 中所有标记为 Python 的围栏代码,并逐段进行语法编译检查;它不会执行示例,因此适合先发现缩进、括号和语法错误。
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预期输出
validated <N> Python example(s)<N> 是文档中 Python 示例的实际数量,具体值可能不同。如果命令抛出 SyntaxError,应先修复对应代码块,再继续语言审校。对于依赖网络、数据库或特定运行环境的示例,还需要在匹配的测试环境中执行,而不能把语法通过当作行为正确。
把链接和改动后的内容重新走查
链接审校不能只看 Markdown 语法是否完整。外部链接需要确认仍然可访问,并优先链接到稳定的官方页面;内部链接还要检查文件移动后相对路径和锚点是否仍然有效。链接文字应描述目标,例如 “See the authentication guide”,而不是大量使用含义不明的 “click here”。
一次修改可能破坏已经通过检查的内容。比如为了统一术语重写句子时,可能误改命令名;调整代码示例后,原来的结果说明也可能失效。因此最后应对所有实质性修改执行一次回归检查:事实改动重新验证事实,代码改动重新运行示例,标题改动重新检查内部锚点。
双重审校的关键不是把技术检查和语言检查机械地各做一次,而是让每个可验证声明都有依据,让每个关键术语只有一种稳定表达。完成这两轮后,文档才同时具备“做得对”和“读得懂”这两个发布条件。