跳到正文

语气与读者称谓

用直接、客观和尊重读者的语言解释技术动作、状态和限制。

用动作带读者往下走

在步骤中直接使用动词,例如“打开项目根目录的配置文件”“保存后重新构建”。需要指定对象时,用“你”指读者,用工具或组件的名称指实际执行者。这样可以分清谁提交配置、谁读取文件,以及谁负责验证。

讲概念时可采用平实的陈述。例如,“构建器把页面标题写入搜索索引。浏览器载入索引后可以匹配标题。”把连续动作拆开能够消除指代,让读者看出数据经过了哪些环节。

用可以验证的说法交代难度和结果

“简单”“轻松”“随时”等词会掩盖读者真正需要的条件。给出要准备的内容、需要检查的地方和实际结果。描述性能时,写明测试输入、环境和测量指标。展示结果随项目规模变化时,可以给出一个可重现的测量方法。

原句改写
你只需简单配置一下。打开 index.config.json,设置输出路径并保存。
显然,你忘记装依赖了。出现“找不到构建工具”时,先检查依赖是否安装。
我们的搜索体验更好。搜索结果会显示命中的页面标题和对应小节。

在失败场景中保留操作空间

用中性措辞描述状态。例如,“索引路径不在构建输出目录中”给出了检查对象。“配置错了”会让读者难以定位原因。说明错误时,从实际观察入手,再给出可重试、可检查的动作。

声明可选行为时,用“可以”表达选择,用条件说明适用场景。涉及必须满足的要求时,用明确的要求等级描述何时需要做以及省略后的结果。