步骤式文档的骨架
面向工程师的文档按「前置条件 → 步骤 → 预期结果 → 排错」组织，每一步动词开头、一步只做一件事，命令可以直接复制执行。这个结构的价值在排错：读者按步执行失败时，能立刻定位到哪一步，而不是在整段描述里找线索。写作时的硬要求是命令原样引用，不要「顺手简化」参数。
基本信息
| 结构 | 前置条件 → 步骤 → 预期结果 → 排错 |
|---|---|
| 步骤写法 | 动词开头，一步一条命令，标注预期输出 |
| 命令 | 原样引用、逐条可复制；改写过的要标为示例 |
| 读者假设 | 会命令行但不懂本系统，术语首次出现给解释 |
典型使用场景
- 功能开启文档：开启访问日志、开启慢查询、开启审计
- 部署与升级手册：含版本前置条件与回滚步骤
- 接口对接说明：鉴权配置、鉴权失败排错路径
- 值班操作卡：每步都能照做，故障时按顺序执行
- 迁移操作单：含数据校验点与失败回退
步骤文档模板
步骤文档模板
写一份“开启访问日志”操作文档：
前置条件：版本要求、需要的权限、影响面提示
步骤：动词开头，一步一条命令；标注每步预期输出
排错：列出 2-3 个常见报错与处理
# 命令原样引用，参数不要改写
命令从素材中原样引用，不要改写参数。
# 影响面单独提示：重启类操作要写明是否中断业务
# 回滚：给出撤销上一步的方法，便于失败时恢复
素材：<notes>……</notes>四段各自要点
| 段落 | 写什么 | 常见缺陷 |
|---|---|---|
| 前置条件 | 版本、权限、影响面 | 漏版本要求，读者在旧版本上执行失败 |
| 步骤 | 一步一条命令 + 预期输出 | 多操作塞进一步，失败时无法定位 |
| 预期结果 | 每步应有的输出或状态 | 缺预期输出，读者无法判断是否成功 |
| 排错 | 常见报错与处理 | 只列报错不写处理动作 |
把多个操作塞进一步会让排错无从定位；一步只做一件事，哪怕步骤数看起来更多。
命令参数被模型「简化」后直接失效，要求原样引用并人工抽查命令块，是这类文档的固定检查项。