3.2 教程与操作指南怎么写

教程与操作指南怎么写

教程文章的完成标准，不是“作者把过程写完了”，而是目标读者能够在对应环境中跟着做、判断每一步是否成功，并在出现常见问题时知道怎样继续。

AI可以把零散操作记录整理成步骤、统一术语并补出可能遗漏的检查点，但它没有实际执行过你的流程时，不能保证按钮位置、命令结果和版本差异都正确。教程写作必须把“生成文字”和“验证操作”分开。

先定义起点和终点

写教程前，先回答两个问题：读者从什么状态开始？做到什么状态才算完成？

以“在电脑上安装某个写作工具”为例，只写“下载安装包并完成安装”远远不够。教程任务卡应更具体：

目标读者：第一次安装桌面软件的普通职场用户
适用环境：已确认的操作系统与软件版本
前置条件：可用账号、网络连接、安装权限、必要磁盘空间
目标结果：软件能够启动，账号登录成功，并完成一次测试输入
不包含：企业批量部署、旧版本数据迁移
验证方式：读者能看到指定界面，并得到与教程一致的测试结果

起点不清，作者会省略自己早已具备的条件；终点不清，读者做到一半也不知道是否已经成功。

一篇可执行教程的基本结构

根据任务复杂度，可以使用下面的结构：

你将完成什么：一句话说明结果，展示完成后的状态；
适用范围：系统、软件、账号类型和教程验证时间；
开始前准备：权限、材料、备份和风险提醒；
操作步骤：每一步只包含一个主要动作；
结果检查：告诉读者如何判断步骤和整体是否成功；
常见问题：按可观察现象提供排查方向；
下一步：说明完成后可以继续做什么。

简单操作不必强行分成七节，但前置条件、动作和完成标志不能省略。

把一个模糊步骤拆开

下面是一条常见但不可执行的写法：

配置好接口信息，运行程序即可。

它隐藏了文件位置、要填写的字段、保存动作、运行目录、命令和成功表现。可以拆成：

### 第1步：复制示例配置

在项目根目录运行：

```bash
cp config.example.json config.json

完成标志：当前目录出现 config.json，示例文件仍然保留。

第2步：填写连接信息

打开 config.json，将 base_url 替换为管理员提供的服务地址，再填写自己的认证字段。不要把真实密钥粘贴到聊天记录或提交到版本库。

完成标志：文件能够正常解析，必填字段不为空。

第3步：运行本地校验

在项目根目录执行指定校验命令。

完成标志：终端显示“校验通过”；如果出现字段错误，先按错误信息修复，不要继续上传。


这个示例中，每一步都有动作对象、位置和完成标志。读者不需要猜“配置好”究竟包括什么。

## 单步写作的六个要素

检查每个步骤是否包含必要信息：

| 要素 | 要回答的问题 |
| --- | --- |
| 位置 | 在哪个页面、目录或设备上操作？ |
| 对象 | 点击、输入或修改什么？ |
| 动作 | 这一步只做哪个主要动作？ |
| 输入 | 值从哪里获得，格式是什么？ |
| 完成标志 | 成功后应该看到什么？ |
| 失败处理 | 没出现预期结果时先检查什么？ |

不要把多个不可逆动作塞进同一步。涉及删除、覆盖、付费、公开发布或权限变更时，应在动作之前给出明显提醒，并说明影响范围与恢复方式。

## 截图要解释信息，不是装饰页面

截图适合说明难以用文字定位的界面，但不能代替关键文字。每张截图至少要做到：

- 裁掉无关区域，保留读者定位所需的上下文；
- 用箭头、编号或高亮指出操作对象；
- 图注说明“在哪里、看什么、做什么”；
- 隐去账号、密钥、客户信息和内部地址；
- 正文仍写出关键按钮名或字段名，方便搜索和无图阅读；
- 界面更新后及时重拍，不用过期截图误导读者。

例如，不要只写“如下图所示”，可以写：“在设置页左侧选择‘连接’，然后在右侧的‘服务地址’输入框填写管理员提供的URL，位置见图2的①。”

如果步骤可以通过一条短命令准确表达，就不必为了形式增加多张截图。图片只在它能降低定位成本时使用。

## 主动处理版本差异

软件教程最容易失效的地方是版本。按钮改名、菜单移动、权限策略变化，都可能让过去正确的步骤无法继续。

教程开头应标明已验证环境，例如：

```text
验证环境：macOS 某版本、软件桌面版某版本
最后验证日期：YYYY-MM-DD
其他系统：核心流程相同，但菜单位置可能不同

如果已知存在两条路径，应分别写清适用条件：

桌面版：在“设置 → 账户”中操作。
网页版：点击右上角头像，再进入“账户设置”。

没有验证过的版本，不要写成“一定相同”。可以标注“以下路径尚未在该版本验证”，并提供官方文档入口或界面关键词，让读者自行确认。

涉及不断更新的产品功能时，写作前应查询官方文档；文章发布后也应记录复查时间。AI凭记忆给出的菜单路径只能作为待验证线索。

排错要从现象出发

“如果失败，请重试”不是有效排错。读者看到的是现象，而不是内部原因，因此常见问题应按现象组织：

现象：运行命令后提示找不到配置文件

依次检查：

终端当前目录是否为项目根目录；
文件名是否确实是 config.json，而不是带隐藏扩展名；
配置是否保存在预期位置；
命令是否支持通过参数指定另一条路径。

现象：配置能读取，但连接失败

先核对服务地址、网络和认证信息，再查看工具返回的具体错误。不要反复提交可能产生重复数据的请求。

排错建议要有安全顺序：先做只读检查，再做可逆修改，最后才考虑重装、清除或覆盖。无法确认原因时，告诉读者需要保存哪些错误信息，以便继续求助。

用AI整理操作记录

最好先由人实际完成一次流程，保留命令、关键界面、输入来源、输出结果和遇到的问题，再让AI整理：

请把以下已验证的操作记录整理为面向〔目标读者〕的教程。

适用环境：〔填写〕
目标结果：〔填写〕
操作记录：〔粘贴〕
已知错误与处理：〔粘贴〕

要求：
1. 开头列出前置条件和适用版本；
2. 每一步只保留一个主要动作，并写明位置、对象和完成标志；
3. 截图位置用“待补图：应展示……”标记，不虚构截图；
4. 排错按读者可见的现象组织；
5. 未经记录验证的步骤标为“待验证”，不要写成必然成功；
6. 不补造按钮、路径、命令输出或产品能力。

AI整理之后，作者要按成稿重新走一遍流程。验证的是“读者看到的教程”，不是脑中熟悉的原流程。

常见失败写法

只有动作，没有条件：读者做到中途才发现缺权限或账号；
一步包含太多动作：其中一处失败后无法判断停在哪里；
只有截图，没有可搜索文字：界面变化或图片不可见时无法继续；
没有完成标志：读者不知道结果是否正确；
把一个版本写成全部版本：未验证路径被表达为通用事实；
排错直接建议重装：跳过了成本更低、更安全的检查。

发布前验收

可以请一位符合目标读者特征、没有参与写作的人试做，然后检查：

不询问作者，也能完成准备工作；
每一步能找到对象，并理解输入从哪里来；
步骤顺序与真实操作一致；
每一步和最终结果都有可观察的完成标志；
截图清楚、已脱敏，图文没有冲突；
版本、环境和未验证范围标注准确；
至少覆盖最常见且可安全处理的失败现象；
危险或不可逆动作提前提示影响。

教程写作不是把“我会做”转成“我写过”，而是把个人熟练操作变成别人能够复现的路径。下一节将从“带读者完成动作”转到“与读者讨论判断”，学习怎样用AI辅助观点评论而不把立场交给AI。