技术英语 / 系统课时
给步骤补上验证结果
给步骤补上验证结果
步骤写到“运行命令”并不等于写完整。读者还需要知道应该看到什么、系统发生了什么变化,以及怎样判断成功。本文把验证结果拆成可观察输出、状态变化和成功条件,并给出可复用写法。
学习目标
- 在操作步骤后补充可核对的预期输出或预期状态。
- 区分控制台输出、持久化状态和退出状态三类验证信号。
- 写出不会把正常差异误判为失败的成功条件。
操作之后必须有判断依据
只有命令而没有验证结果时,读者只能知道“做了什么”,却不知道“做成没有”。尤其是安装、配置和部署文档,命令正常结束并不一定代表目标状态已经建立,因此应选择一个与目标直接相关的信号进行验证。
下面的示例创建配置文件,并检查其中是否存在期望的配置值:
mkdir -p ./demo
echo 'enabled=true' > ./demo/app.conf
grep -q '^enabled=true$' ./demo/app.conf && echo 'configuration ready'预期输出
configuration ready这个输出不是随意添加的一句提示。grep -q 找到完整匹配的 enabled=true 时返回成功状态,随后 echo 才会执行。因此看到 configuration ready,代表本例要验证的配置内容确实存在。
选择最接近目标的验证信号
验证结果通常来自三个位置:控制台输出、系统状态和进程退出状态。应选择最能证明当前步骤目标已经完成的那一种,而不是机械地抄最后一行日志。
| 验证对象 | 适合确认什么 | 文档中的典型写法 |
|---|---|---|
| 控制台输出 | 命令产生了明确结果 | Expected output: configuration ready |
| 文件或服务状态 | 操作改变了持久化状态 | Verify that enabled=true exists in ./demo/app.conf. |
| 退出状态 | 命令是否按程序定义成功完成 | The command should exit with status 0. |
例如,grep -q 本身在匹配成功时不会打印内容。如果文档只写“you should see the matched line”,就与真实命令行为冲突。此时可以描述退出状态,也可以像主示例一样增加一个只用于演示的 echo,把不可见的成功状态转成容易核对的输出。
把预期输出和成功条件分开
预期输出回答“读者可能看到什么”,成功条件回答“满足什么才算完成”。两者经常相关,但不应混为一谈。
本例可以写成:Expected output: configuration ready. The step is successful when ./demo/app.conf contains the exact line enabled=true and the verification command exits successfully.
这种写法比单独写 Success 更可靠,因为它指出了可检查对象。对于存在动态值的输出,例如时间、端口、生成 ID 或临时路径,则不应要求读者逐字符匹配。应明确说明哪些部分会变化,例如将动态时间写成 <TIME>,并把稳定的状态词或结构作为真正的成功条件。
验证失败时让读者知道停在哪里
好的验证步骤还承担故障分界作用。如果没有看到预期结果,读者应在当前步骤处理问题,而不是继续执行后续操作。文档可以直接指出最小检查范围,例如确认文件是否存在、目标值是否写入,以及验证命令是否返回成功状态。
不要把“命令没有报错”当作所有操作的通用成功条件。写文件要检查文件内容,启动服务要检查服务状态或可访问端点,调用接口要检查状态码和响应体。验证对象越接近步骤真正想实现的状态,读者越容易快速判断自己是否可以安全进入下一步。