教程类文章怎么写：让读者照着做就能成

写完一篇教程，自己回看觉得步骤很清楚，读者照着做却卡在第二步：找不到入口、环境版本不对、报错信息没提。问题不在文笔，而在写作时站在了「已经会的人」的位置。

教程类文章的验收标准只有一条：目标读者照着做，能不能在预期时间内得到结果。围绕这条标准，写作顺序、步骤颗粒度、异常处理都要重新安排。下面给一套可以直接照做的流程。

一、先定三件事，再动笔

教程写得乱，通常是这三件事没定就开始了：读者是谁、从什么状态出发、做到什么算完成。三项没定，步骤就会时粗时细。

第三项最容易被省略。很多人写到最后一句「完成」，却没告诉读者完成的样子：是页面上出现某个按钮，还是终端打印某行文字。没有可观察的终点，教程就无法被验收。

第二项决定前置条件写不写。如果读者必须先装好某个环境，这一步要单独列出来，并且写清版本。版本差异是教程失效的头号原因。

第一项则决定用词。读者不熟悉命令行时，「执行以下命令」后面要给出完整命令和预期输出；读者是同行时，可以只给关键参数。同一篇教程服务不了两类人，选一类。

二、步骤的颗粒度：一步一个可验证动作

步骤写得粗，读者会卡；写得细，读者会烦。判断标准不是字数，而是每一步结束时能不能验证。

第三行的结构值得照搬：动作 + 验证现象。每个步骤都带一个「你应该看到什么」，读者就能自己判断是否走对，不必等到最后才发现问题。

步骤编号要连续，不要用「然后」「接着」串联。编号让读者可以中断后回来定位，也方便你在修订时增删。步骤超过十五步，就考虑拆成两篇或者分出阶段。

另一个细节：把耗时写出来。读者对「这一步要等三分钟」有预期，就不会以为卡死了。没有预期的等待，是教程里最常见的放弃点。

三、四类意外必须写进去

教程的价值往往不在顺利路径，而在岔路上。下面四类内容不写，读者一出问题就会离开。

1. 权限与依赖问题。需要管理员权限、需要额外装包、需要开某个开关，都要提前说。
2. 版本差异。界面改版、参数改名、默认值变化，写清适用于哪个版本区间。
3. 常见报错。至少列出三个高频错误，给出「看到这行字就是这个问题」的判断句。
4. 回滚方式。做错了怎么退回上一步，尤其涉及配置修改和数据写入时。

第三项要写成可搜索的形式。读者遇到问题会先搜报错原文，所以错误信息要原样贴出，不要改写成自己的话。后面再跟一句人话解释。

第四项常被省略，但对读者的心理价值极高。知道能退回，才敢往下做。哪怕只是「删掉刚加的配置行，重启即可」，也要写。

这四类内容放在哪也有讲究：前两类放在对应步骤旁边，后两类单独一节放在文末。全部前置会让开头变得很重，读者还没开始就被吓退。

写异常处理时，别只写「如果报错请检查配置」。这种句子对读者没有帮助。要写「检查哪一行、期望值是什么」，具体到能照着核对。

四、发布前的验收：自己走一遍，再找人走一遍

教程的验收不能靠读，只能靠做。下面五步按顺序执行。

1. 清空环境重做一遍。不要在有缓存、有历史配置的机器上验证，那会掩盖缺失的前置条件。
2. 逐步核对验证点。每一步的预期现象是否真的出现，文字描述和实际输出是否一致。
3. 故意制造一个错误。跳过一步或改错一个参数，看文中是否覆盖了这个报错。
4. 找一个目标读者试做。观察他在哪一步停下来问问题，那里就是写得不够清楚的地方。
5. 记录版本与日期。在文首或文末标注适用的软件版本和验证时间。

第一步是最有效的。很多人验证时用的是自己已经配好的环境，所以永远发现不了「新手第一步就卡住」。清空重做虽然麻烦，但能一次暴露大部分问题。

第四步的价值在于旁观。读者提问的位置往往不是最难的步骤，而是你以为「这还用说」的地方。把这些补上，教程的完成度会明显提高。

第五步则是长期维护的基础。软件更新很快，标注了版本，读者才能判断内容是否还适用。相关写法可以对照技术写作怎么写得清楚，两篇讲的是同一套可验证原则。

五、常见问题

教程要不要先讲原理

看篇幅。短教程可以直接给步骤，原理放在文末一节；长教程可以在开头用两百字说明「为什么这样做」，但不要超过总篇幅的一成。读者是来完成任务的，不是来上课的。

截图要多少张

按「看不懂就截」的原则，一般每个关键步骤一张。截图比文字更省认知成本，但要注意打码和标注重点区域，整屏原图反而看不清。

能不能直接放命令让读者复制

可以，而且推荐。代码块要能被完整复制，别在命令中间换行。同时给出执行后的预期输出，方便对照。

教程过时了怎么办

优先更新而不是重写。在文首标注版本与日期，过时部分加提示。完全失效的步骤整段替换。写作前的结构规划可以参考写作前要不要先列大纲，更多方法见写作方法栏目。

小结

教程类文章怎么写，核心是让读者能验证：先定读者基线、起点与终点，再把步骤拆成「动作加验证现象」，把权限、版本、报错、回滚四类意外写进去，最后清空环境自己走一遍。

如果只做一件事：给每一步补一句「你应该看到什么」。补完之后，教程的可执行性会有质的提升。