传统的软件教程，在 AI 时代该与时俱进了

上个月带一个新同事接我们的 Web Service，我很自信地把攒了好几年的家当甩给他：一份 Getting Started 教程、十几个示例项目、一页 FAQ，外加我今年新写的 AI skill。心想这套组合拳够体面了吧。

结果第二天他来问我：“Walter，那个鉴权的 header 到底怎么拼？我照着教程复制过来，401。”我打开教程一看——写得清清楚楚啊，参数、字段、示例一个不少。可他就是跑不通。

那一刻我有点尴尬：我写的不是教程，是一本“说明书”。说明书再全，也代替不了有人站在你旁边，看着你把命令敲进去、报错了帮你改一行。

这篇想说的其实就一句话：传统软件教程那套“文档 + 示例代码”，在 AI 时代已经不够看了。真正该做的，是把教程变成能跑、能问、能纠错的“活教程”——读者一边看一边执行，卡住了有 AI 当场答疑。做到这一步，市面上大多数静态教程都会被甩开一条街。

• 传统教程的病根不是“写得不好”，而是读和做是断开的：你在文档里读，到 IDE 里做，中间那道鸿沟全靠读者自己填。
• AI 时代的解法不是“把文档喂给大模型”，而是把文档、例子、运行环境、AI 助教缝到同一个界面里。

一、我们到底在教什么，又漏掉了什么

先把话说清楚：教别人用一个 Web Service，无非教三件事——

1. 怎么调：API/SDK 的入口、参数、鉴权、返回值。
2. 怎么用：把某个 function 集成进他自己的应用里，解决一个真实问题。
3. 怎么共建（contribute）：怎么改代码、跑测试、提 PR，成为项目的一份子。

传统做法就是给每件事配一份文档加几个示例。听起来很周全，问题出在哪？

出在“读”和“做”之间那道缝。文档是静态的文字，代码在另一个仓库，运行环境要读者自己搭。读者的真实路径是这样的：读一段 → 切到终端 → 复制 → 缺个依赖 → 谷歌一下 → 装好了 → 再回来读 → 又报错……每一次“切出去”，都是一次流失。

静态教程最大的成本，不是写得不够细，而是读者要自己“搭桥”。
桥搭到一半掉下去的人，你永远不知道有多少。

古人说“纸上得来终觉浅，绝知此事要躬行”。放到今天特别应景：躬行的门槛越高，教程的转化率就越低。而传统教程恰恰把“躬行”这一步整个甩给了读者。

二、我自己的三级跳，跳到一半卡住了

这些年我教人用服务的方式，其实一直在升级，可以叫“三级跳”：

第一跳：教程 + 示例代码。最朴素的一套。好处是全，坏处是死——读者得自己搭环境、自己对照、自己 debug。

第二跳：加 FAQ。把大家反复踩的坑收集起来，写成“遇到 X 就查 Y”。这一步很有用，等于把我的“客服记录”沉淀成了知识。但 FAQ 本质是事后补丁，它只覆盖你已经见过的问题，没见过的新坑，读者照样掉。

第三跳：写 AI skill。今年我把教程和例子打包成一个 AI skill，让读者可以直接问 AI：“帮我用这个服务实现一个上传接口。”这一跳很关键——AI 能把散落的教程、例子、FAQ 串起来，按你的具体问题现场组装答案。这是传统文档做不到的。

可跳到这儿，我发现还是差口气：不够直观。

读者问 AI，AI 给一段代码，读者还得复制到自己的环境里跑。跑不通，再回来问。你看，那道“读和做之间的缝”并没有消失，只是从“翻文档”变成了“问 AI”。AI 让找答案变快了，但没让“动手”这件事变近。

这就是我卡住的地方：我一直在优化“怎么把答案给你”，却一直没解决“你怎么当场把它跑起来”。

三、活教程长什么样：把四样东西缝到一个界面里

想通这一点后，我心里那个“理想教程”的样子就清晰了。它不是一份文档，而是一个界面，把四样东西缝在一起：

flowchart LR
    subgraph L["活教程界面"]
        direction TB
        A["讲解: 教程正文 + 概念"]
        B["演示: 交互式引导 + 视频录屏"]
        C["实操: 类 Notebook 边看边跑"]
        D["AI 助教: 随时答疑 + 报错纠正"]
        A --> B --> C
        D -. 贯穿全程 .-> A
        D -. 贯穿全程 .-> B
        D -. 贯穿全程 .-> C
    end
    C --> E["Sandbox: 隔离的运行环境"]
    E --> F["真实返回结果"]

一样一样拆开说，你就明白它凭什么“秒杀”静态教程。

1. Sandbox：让读者不用搭环境就能动手

Sandbox（沙箱）就是一个已经配好、隔离的运行环境——依赖装好了、网络通了，读者点开就能用。

唯一别偷懒替读者省的，是密钥。千万别在共享 sandbox 里预置一把真密钥图省事——那等于把凭证写死在人人能看到的环境里，是安全上的大忌。正确的姿势是让读者当场填自己的 key，或者干脆走 OAuth2 授权：点一下“连接我的账号”，弹出授权页，用户同意后 sandbox 拿到的是限定权限、可随时撤销的临时令牌。这样既保住了“打开就能用”的顺滑，又没把任何人的凭证暴露出去。

这一条直接干掉了传统教程最大的流失点。以前读者读完第一段就要去装 SDK、配环境变量，一半人死在这儿。有了 sandbox，他填一次 key（或点一下授权）就能发第一个请求。门槛从“先搭半小时环境”降到“授权一下、点一下运行”。

通俗点说：以前是给你菜谱让你自己买菜、生火、洗锅；现在是把备好料的灶台推到你面前，你只管翻炒。

2. 页面操作演示：先让读者“看会”，最好还能“跟着做”

不是所有服务都只有 API。很多后台服务还带一个操作页面（控制台、管理后台、配置界面）。教人用 API 可以靠 Notebook，可教人用一个页面，Notebook 就使不上劲了——你总不能让他把“点哪个按钮”写成代码跑一遍。

教一个操作页面，我见过三种形态，效果依次递增：

前两种是老办法，各有各的用。图文指南适合当手册——用户知道自己要干嘛，回来查一步。视频适合降低不确定感——动手前先看一眼“正常应该长这样”，出了偏差自己能察觉。

但最狠的是第三种：交互式引导（就是那种在页面上加一层高亮遮罩、一步步带你走的“产品导览”，技术上像 driver.js、Shepherd.js 干的活）。它的道理和 Notebook 一模一样——把“读”和“做”焊在同一个页面上：代码类用可执行的代码块，界面类用可点击的引导层。用户不是在看别人操作，而是自己在真页面上被牵着手走一遍，走错一步当场有提示，旁边还有 AI 能答“这个开关是干嘛的”。

一句话：教页面别只顾着录视频，能让用户在页面上“跟着点一遍”的引导，比看十遍录屏都强。视频和图文，退居补充位。

3. 类 Notebook 的实操：教程和代码长在一起

这是我最看重的一环。像 Jupyter Notebook 那样，讲解和代码放在同一页，代码块可以直接点“运行”，结果就显示在下面。

它的杀伤力在于把“读”和“做”焊死在了一起：

• 读者不用在文档、IDE、终端之间反复横跳，注意力不流失。
• 每个知识点后面就跟着一个能跑的代码块，读完立刻验证，即时反馈。
• 代码可以改——把示例里的参数换成自己的，马上看到不同结果。学习本来就该是“调着玩”出来的。

对讲“怎么调 API”这种任务，这几乎是完美形态：读一句“加上这个 header”，下面就是一个带 header 的请求，点一下，200，返回体亮在眼前。知道和做到之间的距离，被压缩到了一次点击。

4. AI 助教：把 FAQ 从“事后”变成“实时”

前面三样解决了“正常路径”，可人总会走岔。这时候 AI 助教上场——它贯穿整个界面，随时能问：

• 答疑：“这个参数是干嘛的？”“为什么要先拿 token？”当场解释。
• 纠错：读者的代码报错了，AI 直接看着错误信息告诉他哪行错了、怎么改。这就是把 FAQ 从“事后翻查已知问题”升级成了“实时诊断未知问题”。
• 改写：“帮我把这个示例改成上传文件的。”AI 基于当前上下文改，读者接着跑。

我之前写的那个 AI skill，其实就是这一环——只是当时它是孤立的，飘在教程外面。把它接进这个界面，让它能看到读者正在跑的代码和真实的报错，威力完全不一样。

5. 拼起来长这样：给应用加一个“语音转文字”功能

光说四样零件太抽象。我举个更像真实工作的例子：读者是个后端开发，想给自己的客服系统加一个功能——把用户上传的语音留言自动转成文字。他要学的不是背 API 字段，而是把我们的转写服务真正接进他的代码里。做成活教程，他打开的是一个能跑代码的页面，从上到下大概是这样。

开头先放一段 30 秒录屏，演示一件纯靠文字讲不清的事：怎么在控制台建一个应用、勾上“转写”权限、拿到 OAuth 凭证。这部分是页面操作，交给视频最省事。看完点右上角“连接账号”授权，token 就注入了 sandbox——他不用把任何密钥抄进代码。

往下是第一个可运行的代码格（sandbox 里依赖装好了，连示例音频都备好了）：

import os, requests

BASE = "https://api.example-speech.com/v1"
# OAuth2 授权后自动注入，别把令牌写死在代码里
headers = {"Authorization": f"Bearer {os.environ['SPEECH_TOKEN']}"}

# sandbox 自带一段示例音频，直接上传，拿一个任务号
with open("sample-zh.wav", "rb") as f:
    r = requests.post(f"{BASE}/transcriptions",
                      headers=headers,
                      files={"audio": f},
                      data={"language": "zh"})
r.raise_for_status()
job_id = r.json()["job_id"]
print(job_id)          # → 'job_7c3e1a'

点运行，下面立刻打印出 job_7c3e1a。读者顺手接着写第二格——这里几乎人人都会踩同一个坑：上传完就急着取结果。

result = requests.get(f"{BASE}/transcriptions/{job_id}", headers=headers).json()
print(result)
# → {'status': 'processing', 'text': None}    # 咦，文字怎么是空的？

搁传统教程，读者到这儿就懵了：没报错，也没结果，文档翻半天也不知道自己错哪了。而活教程里，页面旁边的 AI 助教看着他刚跑出来的这个 processing，直接点破：

🤖 没错，这一步返回 processing 是正常的——转写是个异步任务，上传后服务在后台跑，不会立刻好。你有两种拿结果的姿势：小文件就轮询（隔两秒查一次，直到 status 变 done）；生产环境更推荐配 webhook，让它转完主动回调你，别让你的线程干等。要不要我把轮询那段替你写好？

读者说“好”，AI 就地把第三格补上：

import time
while True:
    result = requests.get(f"{BASE}/transcriptions/{job_id}", headers=headers).json()
    if result["status"] == "done":
        break
    time.sleep(2)                       # 小文件够用；量大改用 webhook
print(result["text"])
# → '各位好，欢迎参加今天的产品评审……'

到这一步，读者不只是“调通了一个 API”，而是亲手把整条链路跑通了，还顺带搞懂了异步任务这个真实世界里绕不过去的坑。最后一格顺理成章——把它包成一个函数，就能塞进他自己的客服系统：

def transcribe(path, language="zh"):
    with open(path, "rb") as f:
        job = requests.post(f"{BASE}/transcriptions", headers=headers,
                            files={"audio": f}, data={"language": language})
    job.raise_for_status()
    job_id = job.json()["job_id"]
    while True:
        res = requests.get(f"{BASE}/transcriptions/{job_id}", headers=headers).json()
        if res["status"] == "done":
            return res["text"]
        time.sleep(2)

回头看这一节，四样零件全用上了：视频教会他控制台那几下点击，sandbox 免了他搭环境、抄密钥，Notebook 让他一格格边看边跑、还能改了再试，AI 助教在他撞上异步坑的那一刻当场救场——不是背一句“401 怎么办”，而是顺着他真实的代码和返回，把一个真实的设计问题讲明白，还替他把代码补齐。

读、做、踩坑、纠错、集成，全在一个页面里闭环。这，才是我说的“秒杀”静态教程的地方。

四、凭什么说它“秒杀”传统教程

不是我吹。把两种教程摆到一张表上，差距一目了然：

最后一行值得多说一句。传统教程有个老毛病：文档和代码会“过期分手”。服务升了个版本，示例代码悄悄失效，可文档还是老样子，读者照着做全是坑。而活教程里的代码块是真在 sandbox 里跑的——它一旦失效，你自己第一个发现，而不是等读者来投诉。教程从“需要人去校对的死文字”，变成了“会自己报警的活系统”。

这就是质变：传统教程是说明书，活教程是陪练。说明书再详尽，也比不上一个站在你旁边、看着你操作、随时纠正你的教练。

五、想落地，可以这么起步

道理不复杂，但真要做也别一上来就憋大招。我的建议是分层加料，先解决流失最狠的环节：

1. 先上 Sandbox，堵住第一个流失点。
   哪怕只是一个预置好依赖、网络的在线环境（密钥让用户自己填或走 OAuth2 授权，别预置真凭证），让读者“授权一下就能发第一个请求”，转化率立竿见影。这一步性价比最高。

2. 把核心教程改造成可执行的 Notebook。
   挑最高频的三五个场景（鉴权、第一个调用、一个典型集成），把讲解和可运行代码块合到一页。别贪多，先把“黄金路径”跑通。

3. 有操作页面的，优先做交互式引导，其次才是录屏。
   凡是“文字讲不清、要在页面上点”的地方——控制台配置、拿密钥、看日志——先想能不能加一层引导，让用户在真页面上跟着点一遍；实在来不及，退而求其次录个 30 秒短视频。不用精致，讲清楚就行。

4. 把 AI 助教接进上下文。
   让 AI 能读到读者当前的代码和报错，而不是让它在教程外面干聊。这一步是把你之前写的教程、例子、FAQ、skill 真正激活的关键。

5. 补一条“别过度工程”的红线。
   不是每份文档都值得做成活教程。只给“高频、易错、转化重要”的核心路径做——比如 Getting Started、核心 API。冷门的边角功能，一段静态文档足矣。做交互式教程是有维护成本的，别为了炫技把自己拖垮。

一句话：

别再优化“怎么把答案讲得更全”，改去缩短“读者从看懂到跑通”的那段距离。
缝隙缝到哪里，转化率就长到哪里。

六、动手做：演示视频和交互式教程怎么搓出来

上面都是“为什么”，这一节全是“怎么做”。两块最花功夫的——演示视频和交互式教程——我把工具、步骤和坑都摆出来，你可以直接照着抄。

演示视频：短、聚焦、易替换

先立个规矩：一段视频只讲一件事，控制在 30～90 秒。“三分钟带你上手”听着周全，实际没人看完，改版了还得整段重录。宁可拆成五段各 40 秒，坏一段补一段。

工具（按场景挑，别贪多）：

• 图形界面操作：录屏用 OBS Studio（免费、跨平台）、Loom（录完自动生成链接和字幕，适合快速产出）、macOS 上的 CleanShot X / ScreenFlow（能放大光标、加标注）。
• 命令行操作：用 asciinema 或 terminalizer——它录的是文本不是视频，读者能直接复制里面的命令，体积还小得多。命令行教程千万别录成视频，那等于把可复制的文字变成了截图。

方法（这套流程能少走很多弯路）：

1. 先写脚本再录。把每一步操作和要说的话列成分镜，别即兴——即兴录出来全是“嗯……然后我们点这个……”的废话和卡顿。
2. 录之前清场。关通知、用干净的演示账号、把浏览器缩放调到能看清的字号。真密钥、真邮箱一律打码或换成假数据。
3. 关键动作放慢、加标注。要点几下的地方慢一点，鼠标停顿一下；用高亮圈或箭头指出“就点这里”。
4. 默认加字幕，慎用真人配音。字幕让人静音也能看懂，还方便做多语言；真人配音一改版就得重录，维护成本高。字幕和脚本现在都能让 AI 直接生成。
5. 能用 GIF 就别用视频。几秒钟的循环操作（点个开关、切个 tab），做成 GIF 嵌在文档里，读者不用点播放就看到了。

一句话记住：给视频“瘦身”，你才愿意在 UI 改版后老老实实去更新它。没人愿意维护的演示，很快就变成误导。

交互式教程：分两种，别用错工具

前面说过，交互式教程分两类，用错工具是最常见的坑——别拿讲代码的工具去教点按钮，反之亦然。

第一类·页面操作 → 引导层（product tour）

就是在真实页面上盖一层高亮遮罩，一步步“点这里、填这个”，用户跟着走。

• 工具：轻量自建用 driver.js、Shepherd.js、Intro.js（开源、几十行就能配一个 tour）；不想自己写、要数据统计的，用 Appcues、Pendo、Userpilot 这类商业方案。
• 方法：把每一步定义成“选择器 + 文案 + 高亮区域”，锚定到页面元素，分步推进，每步允许跳过和重来。关键是要让用户真的点一下才进下一步，而不是纯翻页——“跟着做”和“看着走”的差别就在这。
• 头号坑：别用 CSS class 或 DOM 结构当锚点，页面一改版引导就全断了。给需要引导的元素加一个稳定的 data-tour-id 属性专门定位，前端重构也不影响。

第二类·代码实操 → 可执行 Notebook / 沙箱

就是前面例子里那种讲解和可运行代码块交替、点一下就出结果的形态。

• 纯前端方案（最省事，无需后端）：JupyterLite（Python 直接在浏览器里用 WebAssembly 跑）、StackBlitz WebContainers 和 CodeSandbox Sandpack（在浏览器里跑 Node/前端项目）、Observable（跑 JS）。教程站直接嵌一个可编辑可运行的代码框，用户改了就能跑。
• 要真后端环境（跑真实 SDK、连真服务）：每个用户开一个隔离容器，务必配上三样护栏——超时（跑太久自动杀）、资源上限（CPU/内存/磁盘封顶）、网络白名单（只放行你的服务域名，别让沙箱变成别人的免费矿机）。用完即毁。这几条不是可选项，是安全底线。
• 别自己造轮子：已经有 Google Colab、Jupyter 这类成熟方案，能白嫖就别自建执行后端——那是个无底洞。

让 AI 帮你做这些：AI 不只是给读者当助教，也能给你当帮手——从代码自动生成讲解文案、给视频生成字幕和脚本、甚至根据你录的一段操作反推出引导步骤的初稿。生产环节能省一大半力气。

一张“活教程”自检清单

做之前对着过一遍，能少踩八成的坑：

• [ ] 每段演示视频只讲一件事，≤ 90 秒，静音看字幕也能懂？
• [ ] 命令行演示用了 asciinema 这类可复制文本，而不是录成视频？
• [ ] 视频里的真密钥、真账号都打码或换成假数据了？
• [ ] 引导层锚点用的是稳定的 data-tour-id，不是易变的 class？
• [ ] 引导是让用户“跟着点”，而不是纯翻页看？
• [ ] 代码沙箱配齐了超时、资源上限、网络白名单三道护栏？
• [ ] 密钥是用户自己填或 OAuth2 授权，没有预置真凭证？
• [ ] AI 助教能读到用户当前的代码和真实报错，而不是在旁边干聊？
• [ ] 只给高频、易错、转化重要的核心路径做——没为炫技过度工程？

最后一句

回头看我那位卡在 401 的新同事——问题从来不是我教程写得不够细，而是他读的时候我不在场。传统教程的宿命就是这样：作者和读者永远错开时空，你写下的每一个字，都在赌读者不会在你没预料到的地方掉队。

AI 时代给的最大礼物，恰恰是把作者“搬到读者身边”：sandbox 替你把环境铺好，Notebook 替你把手把手的节奏还原，AI 助教替你 24 小时守在读者旁边答疑纠错。你写一次教程，就等于同时坐在了一千个读者的电脑前。

所以别再问“我的文档写全了吗”，改问一句更狠的：

一个从没用过我服务的人，能不能打开这一页，不装任何东西，十分钟内亲手跑出第一个成功的结果？

答不上来“能”，那教程就还停在说明书时代。

全文思维导图

@startmindmap
<style>
mindmapDiagram {
  node {
    BackgroundColor #F8F9FA
    RoundCorner 10
    Padding 10
    FontSize 13
  }
  :depth(0) {
    BackgroundColor #1E3A5F
    FontColor white
    FontSize 18
    FontStyle bold
  }
  :depth(1) {
    FontSize 15
    FontStyle bold
  }
  :depth(2) {
    FontSize 13
  }
}
</style>

* AI 时代的软件教程
** 传统教程的病根
*** 读和做是断开的
*** 环境要读者自己搭，流失严重
*** FAQ 只是事后补丁
*** 文档和代码会过期分手
** 我的三级跳
*** 教程+示例（全但死）
*** 加 FAQ（事后补丁）
*** 写 AI skill（能串联但不直观）
*** 卡点：优化了给答案，没缩短动手
** 活教程 = 四样缝到一个界面
*** Sandbox：零配置就能动手
*** 演示：教代码用 Notebook，教页面用交互式引导
*** 类 Notebook：教程与代码合一
*** 页面：交互式引导>视频>图文
*** AI 助教：实时答疑纠错
** 凭什么秒杀
*** 环境零准备
*** 读做合一、即时反馈
*** AI 应对没预设的问题
*** 代码在跑，失效自己先发现
** 落地步骤
*** 先上 Sandbox 堵流失
*** 核心教程改可执行 Notebook
*** 关键操作补 30 秒录屏
*** AI 助教接入上下文
*** 红线：别过度工程，只做核心路径
** 怎么做
*** 视频：短≤90秒、加字幕、能用GIF就别录像
*** 命令行用 asciinema（可复制文本）
*** 页面引导：driver.js/Shepherd，锚点用 data-tour-id
*** 代码沙箱：JupyterLite/Colab，配超时+资源+网络白名单
*** 让 AI 帮你生成脚本/字幕/引导步骤
** 最后一问
*** 陌生人能否 10 分钟零安装跑出第一个结果
@endmindmap

本作品采用知识共享署名-非商业性使用-禁止演绎 4.0 国际许可协议进行许可。 欢迎在我的个人网站 https://www.fanyamin.com 访问原文并评论。