技术英语 / 系统课时
搭出英文文档的第一版
搭出英文文档的第一版
第一版英文文档不追求句句精修,而要先让读者完成任务。本节用“目标、步骤、验证、限制”的顺序搭出可运行的骨架,并把命令、示例和注意事项放到最需要的位置,再统一润色语言。
学习目标
- 按读者任务而不是中文原文顺序组织章节
- 写出可执行的关键步骤,并紧邻给出验证结果
- 用限制和注意事项阻止读者在错误条件下继续操作
先确定读者要完成什么
先用一句话定义读者完成文档后应该得到什么结果,例如“在本机启动示例服务并确认它能输出就绪状态”。如果一个文档同时包含安装、配置、部署和故障排查,第一版应先围绕主任务组织,其余内容按依赖关系放到后面,而不是照搬原始资料的记录顺序。
正文中的每一节都应回答一个行动问题:开始前需要什么、具体做什么、怎样确认成功、什么情况下不能这样做。这样即使英文还不够自然,文档也已经具备可执行性。
先写关键动作和验证
命令应出现在读者需要执行它的位置,随后立即说明成功时能观察到什么。下面用一个最小命令演示这种写法。
python3 -c 'print("service ready")'预期输出
service ready在正式文档中,命令前要说明目的,命令后要给验证结果。不要把所有命令堆到一个章节,再把所有结果集中到另一个章节,否则读者很难判断自己在哪一步出了问题。
用短句完成第一版英文
第一版优先写短而确定的句子。一个段落只承担一个功能,例如动作、结果或限制,不要把背景、步骤和异常处理塞进同一句。
可以先采用稳定句型:
- 动作:
Run the following command to start the service. - 验证:
The command prints service ready when the check succeeds. - 条件:
Use this procedure only on a local development machine. - 限制:
The example does not configure authentication.
这些句型不是最终文风模板,而是用来保证信息角色清楚。等结构稳定后,再统一调整术语、语态和句式,效率通常高于边写边润色。
把示例和注意事项放在决策点
示例应解决当前步骤最可能出现的理解问题,而不是为了“文档看起来完整”而存在。注意事项也应靠近触发它的操作,例如在会覆盖数据的命令之前提醒,而不是在文末单独堆一组警告。
当一个限制只影响某一步,就写在该步附近;只有真正跨越全文的前置条件,才适合放在开头。这样读者不需要记住远处的规则再回来执行当前操作。
检查第一版是否已经可发布
第一轮不要先挑语法细节,而应先走完整个读者路径:前置条件是否齐全,命令能否复制执行,示例是否与说明一致,成功结果是否可观察,限制是否出现在决策之前。
如果这些条件都满足,再做第二轮语言编辑:统一术语、缩短长句、删除重复背景、修正冠词和时态。一个结构正确、事实准确的朴素英文初稿,比措辞漂亮但步骤缺失的文档更接近真正可发布的版本。