技术英语 / 系统课时
用工具做最后一轮校对
用工具做最后一轮校对
人工通读适合判断语义和表达,但很容易漏掉拼写错误、Markdown 结构问题和失效链接。发布前应把不同工具串成一条短检查链,让机器先拦截可机械发现的问题,再由人工处理语境、术语和技术准确性。
学习目标
- 区分拼写、语法、Markdown 与链接检查各自能发现的问题
- 组合一条可重复执行的发布前校对命令
- 根据工具失败类型决定修复、忽略还是人工确认
把工具分成四道检查
不同工具负责不同问题,不能互相替代。拼写检查适合发现单词拼错和未收录术语;语法检查更适合句子层面的主谓一致、冠词和重复用词;Markdown 检查关注标题层级、列表缩进和代码围栏;链接检查则验证 URL 是否仍可访问。
工具产生的告警只是线索,不是自动改写许可。像 Kubernetes、gRPC、OAuth 这类词可能被普通拼写器标红,但正确处理通常是加入项目词典,而不是把术语改成相似的普通单词。语法工具也可能误判 API 名称、命令片段或刻意简短的标题。
准备最小检查链
下面示例假定项目已在开发依赖中安装 cspell、markdownlint-cli2 和 markdown-link-check,文档位于 docs/。命令使用 set -e,任何一步失败都会立即停止,避免后续的“通过”提示掩盖前面的错误。
set -e
npx cspell "docs/**/*.md" >/dev/null
npx markdownlint-cli2 "docs/**/*.md" >/dev/null
find docs -name "*.md" -print0 | xargs -0 -n1 npx markdown-link-check -q >/dev/null
printf 'proofread checks passed\n'预期输出
proofread checks passed只有三类检查都返回成功状态时才会打印这行文字。实际执行中,失败的工具会在终端给出自己的错误信息;不同版本的日志格式可能不同,因此应以退出状态和具体报错位置为准。
按失败类型处理
拼写错误先判断是普通单词拼错,还是合法术语未入词典。前者修正文案,后者加入项目词典,并尽量避免全局忽略过于宽泛的词。
Markdown 错误应优先修复结构本身,例如跳级标题、未闭合代码围栏或错误列表缩进。若团队明确允许某条规则的例外,应在项目配置中集中关闭或调整,不要在正文里散布大量局部忽略标记。
链接失败需要区分三种情况:链接确实失效、目标站点临时不可用、站点拒绝自动探测。第一种应更换或删除链接;后两种要人工在浏览器中确认,再决定是否加入检查器的忽略规则。对外部网站使用永久“忽略”前,应确认这不会让真正的失效链接长期漏检。
把检查固定到发布流程
最后一轮校对的顺序应稳定:先运行机器检查,再修复确定性问题,然后人工通读语义与技术事实,最后重新运行全部检查。这样可以避免人工修改后又引入新的 Markdown 或拼写问题。
如果项目已经有 CI,可以把同一检查脚本放入拉取请求检查中,让本地与 CI 使用完全相同的命令。发布条件不应是“没有任何工具警告”,而应是“所有可解释的告警都已处理”:错误已修复,合法术语已登记,必要例外有明确规则,外部链接已人工确认。
工具最适合发现重复、机械且可定位的问题;术语是否准确、句子是否自然、说明是否真的帮助读者理解,仍需要人工判断。把两者组合起来,才能让最后一轮校对既快又可靠。