直接写读者要做的事
用自然的简体中文。操作步骤从具体动词开始,比如“打开配置文件”“运行构建命令”。需要明确动作主体时,用“你”指读者,用组件、服务或系统的名称指动作的执行方。
把条件写在动作前,把动作结果写在动作后。把“通常很快”“很容易配置”等概括改为读者能判断的事实。需要说明耗时时,给出适用环境与测量条件。
| 原句 | 改写 |
|---|---|
| 对该配置项进行设置后即可完成启用。 | 将 cache 设为 true,然后重启服务。 |
| 只需填写几个字段就可以快速完成。 | 填写服务地址和项目名称,保存后刷新页面。 |
| 系统会进行处理。 | 构建器读取配置文件并生成静态资源。 |
保持术语稳定
优先使用项目术语表和界面上的实际用词。同一个概念在正文、图表、示例和导航中使用同一名称。用 useFetch 这样的代码标识符时,保留上游大小写。产品名按官方拼写,例如 GitHub、Node.js 和 TypeScript。
专业缩写首次出现时,按读者需要给出中文全称和缩写,例如“服务端渲染(SSR)”。后文可以用缩写。容易混淆的词应在首次使用时交代含义,例如“部署”指把构建结果发布到运行环境。
区分要求、建议和选项
用“必须”表达成立条件,用“建议”表达通常较合适的做法,用“可以”描述可选能力。涉及限制时,写明版本、平台、权限或数据范围。
《中文技术文档写作风格指南》的语言风格章节提供了更多面向读者的改写示例。
用词要对应具体行为
写“确认”时给出读者可以观察的状态。写“启用”时说明由哪个开关或操作改变行为。描述兼容性时,把“支持”与明确的版本或输入组合使用。
| 原句 | 改写 |
|---|---|
| 请确保权限正确。 | 确认当前账号可写入输出目录。 |
| 此参数支持自动处理。 | 省略 --output 时,构建器使用配置文件中的输出路径。 |
| 请合理设置超时。 | 将 timeoutMs 设为 100 到 500 之间的整数,单位为毫秒。 |
同一个词在多个位置使用时,先核对含义和动作是否一致,再按术语、缩写与命名统一写法。
从草稿查到具体规则
| 读起来不顺的地方 | 可以怎样核对 |
|---|---|
| 读者找不到从哪里开始 | 在语气与读者称谓中查直接给动作和位置的写法 |
| 一句包含多个条件或结果 | 按句式和语法拆开可独立核对的事实 |
| 译名或大小写不一致 | 按术语、缩写与命名对照项目术语表和实际界面 |
| 页面很长,结果难以查找 | 用标题、段落与目录设计可以直接进入的小节 |
从一个真实段落开始,找出读者首先需要的条件和动作。改写后检查示例和标题是否使用同一套说法。可以对照完整改写案例,从识别缺失信息一直核对到执行结果。