跳到正文

语言风格与用词

用清楚的动作、稳定的术语和可核对的条件写简体中文技术文档。

直接写读者要做的事

用自然的简体中文。操作步骤从具体动词开始,比如“打开配置文件”“运行构建命令”。需要明确动作主体时,用“你”指读者,用组件、服务或系统的名称指动作的执行方。

把条件写在动作前,把动作结果写在动作后。把“通常很快”“很容易配置”等概括改为读者能判断的事实。需要说明耗时时,给出适用环境与测量条件。

原句改写
对该配置项进行设置后即可完成启用。将 cache 设为 true,然后重启服务。
只需填写几个字段就可以快速完成。填写服务地址和项目名称,保存后刷新页面。
系统会进行处理。构建器读取配置文件并生成静态资源。

保持术语稳定

优先使用项目术语表和界面上的实际用词。同一个概念在正文、图表、示例和导航中使用同一名称。用 useFetch 这样的代码标识符时,保留上游大小写。产品名按官方拼写,例如 GitHub、Node.js 和 TypeScript。

专业缩写首次出现时,按读者需要给出中文全称和缩写,例如“服务端渲染(SSR)”。后文可以用缩写。容易混淆的词应在首次使用时交代含义,例如“部署”指把构建结果发布到运行环境。

区分要求、建议和选项

用“必须”表达成立条件,用“建议”表达通常较合适的做法,用“可以”描述可选能力。涉及限制时,写明版本、平台、权限或数据范围。

《中文技术文档写作风格指南》的语言风格章节提供了更多面向读者的改写示例。

用词要对应具体行为

写“确认”时给出读者可以观察的状态。写“启用”时说明由哪个开关或操作改变行为。描述兼容性时,把“支持”与明确的版本或输入组合使用。

原句改写
请确保权限正确。确认当前账号可写入输出目录。
此参数支持自动处理。省略 --output 时,构建器使用配置文件中的输出路径。
请合理设置超时。将 timeoutMs 设为 100 到 500 之间的整数,单位为毫秒。

同一个词在多个位置使用时,先核对含义和动作是否一致,再按术语、缩写与命名统一写法。

从草稿查到具体规则

读起来不顺的地方可以怎样核对
读者找不到从哪里开始在语气与读者称谓中查直接给动作和位置的写法
一句包含多个条件或结果按句式和语法拆开可独立核对的事实
译名或大小写不一致按术语、缩写与命名对照项目术语表和实际界面
页面很长,结果难以查找用标题、段落与目录设计可以直接进入的小节

从一个真实段落开始,找出读者首先需要的条件和动作。改写后检查示例和标题是否使用同一套说法。可以对照完整改写案例,从识别缺失信息一直核对到执行结果。