技术英语 / 系统课时

让命令说明和代码对得上

让命令说明和代码对得上

技术文档里最危险的错误之一,是正文说一个参数、示例却运行另一个参数。本文用可执行命令演示如何让参数、路径、变量名和说明逐项对齐,并建立修改后的核对方法。

学习目标

  • 让命令中的选项、参数、路径与英文说明保持逐项一致。
  • 识别“文字已经改了,但示例没有同步”的常见错位。
  • 用可执行结果检查文档描述是否仍然准确。

从命令本身提取事实

写命令说明时,不要先凭印象描述功能,再去寻找一个看起来类似的示例。更稳定的方法是以最终可执行命令为事实来源,逐项确认程序名、选项、参数值、路径以及执行结果。

下面的命令创建一个配置文件,再查找其中的 timeout 配置:

bash
mkdir -p ./config
echo 'mode=production' > ./config/app.conf
echo 'timeout=30' >> ./config/app.conf
grep -n -F 'timeout' ./config/app.conf

预期输出

text
2:timeout=30

这里的实际事实很明确:grep 搜索的是字面文本 timeout,-F 表示按固定字符串匹配,-n 要求打印行号,读取的文件是 ./config/app.conf。因此英文说明可以写成:Run grep -n -F 'timeout' ./config/app.conf to find the literal text timeout and print its line number.

实际行号会随着文件内容变化;本例固定写入两行,因此预期结果为第 2 行。

让每个命令元素都有对应说明

命令和正文不必逐字符复述,但影响行为的元素不能在说明中变成另一套名字。尤其要检查选项、路径和变量,因为它们最容易在修改示例后留下旧描述。

命令元素 本例含义 说明中需要保持一致的内容
grep 执行文本搜索 不要描述成读取 JSON、解析配置等其他动作
-n 输出匹配行号 如果正文声称只输出内容,就遗漏了可见行为
-F 把模式当作固定字符串 不要写成 regular expression search
'timeout' 搜索目标 不应在正文改成 mode 或其他名称
./config/app.conf 输入文件 路径必须与示例完全一致

参数的解释也应使用与代码相同的术语。例如命令里叫 timeout,正文就应继续称为 timeout setting;没有必要为了避免重复而改成 delay、wait time 等近义词。技术写作中的术语稳定性通常比语言变化更重要。

修改示例时同时修改说明

最常见的错位来自局部修改。作者可能把文件从 ./app.conf 移到 ./config/app.conf,或者把搜索内容从 mode 改成 timeout,却只更新代码块。此时每一部分单独阅读都像是正确的,合在一起却无法执行。

修改命令后,可以按“程序名 → 选项 → 参数值 → 路径 → 输出”的顺序重新读一遍正文。凡是正文出现的技术标识符,都尝试在代码或实际结果中找到对应项;反过来,命令中会改变行为的重要选项,也应确认读者能够从文字中知道它为什么存在。

用执行结果反查描述

最后不要只做文字对照,还要运行示例。若命令得到 2:timeout=30,说明至少可以确认文件路径存在、搜索目标正确、固定字符串匹配生效,并且 -n 确实产生了行号。

如果实际输出与文档声称的结果不同,应优先确定哪一边才是当前真实行为,再统一更新命令、说明和预期结果,而不是只修补其中一句。这样可以让读者看到的文字、复制的命令和得到的结果始终描述同一个操作。

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

目录与阅读设置

阅读设置

17

记录一个想法

让命令说明和代码对得上

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

登录哪都通