博客写作规范：从一篇范文拆出的可执行清单
笔记 · 写作方法论
本文回答一个问题：同样是实验记录，为什么有的文章读起来一层层往上走，有的读起来像在泥里蹚？ 答案不靠感觉，靠解剖——把一篇公认的范文逐段拆开，看它每一处手法在干什么，再把手法固化成任何人都能对照执行的清单。
一、为什么需要一篇「规范」
写博客最常收到的反馈是：「内容都对，但读起来难受。」难受在哪，作者自己往往说不清——因为写作时的心智状态（刚跑完实验、满脑子细节）和阅读时的心智状态（一无所知、需要被牵着走）完全是两回事。
实验日志的顺序 ≠ 读者的顺序。作者是「先跑通再理解」，读者要「先理解再看你跑通了什么」。规范的全部意义，就是把这两条顺序掰开重排。
解剖标本：《从零理解 Docker 镜像分层——两个目录叠出一个文件系统》（Docker 系列第 22 篇，下文称「范文」）。选它不是因为完美，而是因为它把「循序渐进」四个字落到了每一段的执行层。下文每条手法都标注它在范文里的原位。
十八条手法，按文章的物理顺序分成四组：开篇 3 条、正文推进 9 条、事实纪律 3 条、收尾 3 条。
二、开篇：三条手法定生死
读者决定读不读下去，就在开篇。范文用了三招：
1. 先给「为什么要学」，再给定义
范文的「写在前面」不是定义 UnionFS，而是先坦白：「『联合文件系统』几个字拆开都认识，合起来不知道在说什么」——然后立刻把好处挂出来（400 MB 镜像 10 台共用、改一行秒级重建，凭什么？）。
定义是答案，痛点才是问题。读者为问题停留，不为答案停留。
2. 路线图一条线，走到哪算哪
范文列出课程路线：
① 两个目录 → ② 叠到一起 → ③ 写落在谁家 → ④ 改楼下的文件 → ⑤ 删除是挡板 → ⑥ 真容器就是这套 → ⑦ 层从哪来 → ⑧ 缓存 → ⑨ 老教程的 AUFS
这一行字值一篇好文章的一半：读者随时知道「我在哪、还剩多少」。没有它，读者在长文里的默认感受是迷路。
3. 环境与官方入口先行
开篇末尾一句话交代：WSL2 Ubuntu-22.04（root）+ Docker 29.1.3，实验目录 /root/union-lab，官方入口链接。环境差异影响结论的文章（Linux/容器/网络几乎全部如此），这一行是「可照抄操作手册」的前提。
三、正文推进：九条手法，一次一层
4. 每课只讲一个概念，一步不跳
范文九课，每课一个概念，第一课居然只是「建两个目录、各放一个文件」。学生问「就这？」，老师的回答值得抄进任何一篇教程：
「算，而且是全文最重要的一课。接下来所有东西都从这两个目录长出来，一步都不跳。」
砍掉第一课的冲动人人都有一挥刀的理由——「太简单了」。但读者掉队恰恰发生在作者觉得「显然」的跳步处。
5. 从你已经会的东西开始
联合挂载的入口不是内核文档，是两个普通目录——读者已有的东西。从已知到未知不是口号，是每次引入新概念时的强制动作：新概念的第一个例子，必须搭在读者已会的东西上。
6. 命令逐段拆解表
范文第一次给出 mount -t overlay 命令后，紧跟一张表，把命令拆到段：
| 段 | 含义 |
|---|---|
-t overlay | 用 overlay 这类文件系统来挂 |
lowerdir=… | 参与叠加的下层目录 |
| …… | …… |
长命令不拆解，读者只能「照抄能用、换就报废」。拆解表是「会用」和「背会」的分界线。
7. 输出殿后，且先说看哪
范文贴输出前永远先说看哪：「三行输出逐个看」「先说看哪几行，再逐类读」「注意看：sleep2 出现在视图里，而 company 纹丝不动」。
输出甩脸（先贴一大坨再解释）是「读起来难受」的第一大根因——正确顺序是：先给读者一个预期，输出只是替你作证。
8. 一句话总结收口
每课结尾一条 blockquote：「视图里写新文件 = 直接写进上层；下层只是垫着看的。」 用等式/对仗把本课压成一句能背下来的话。读者复盘时扫一遍这些句子，等于把全文重读了一遍。
9. 比喻一个用到底，每个比喻只服务一个概念
范文的比喻账本：透明胶片（联合视图）、单向门（只读层）、图书馆复印（写时复制）、不透明贴纸（whiteout）、教材与草稿本（镜像与容器）。
注意纪律：比喻不混用、不升级、不复用。胶片从头到尾只解释「叠加」，一旦让它再去解释「删除」就会破——那时候换贴纸上场。
10. 易混点单独成块，配实测
「只读层的只读，是挂载角色还是文件权限位？」——范文没有用文字辩，而是当场绕到宿主机改楼下文件，改动立刻反映进视图，误会不攻自破。
易混点是读者「以为懂了」的重灾区。规范要求：每个易混点独立成块（不要揉进正文）、必须有一个实验性的判别动作。
11. 插问、检查、留题——给对话感装上牙齿
范文三种互动各有分工：
- 学生插问（workdir 干嘛的？9 和 8 对不上？）——替读者问出「不好意思问」的问题；
- 课堂检查回放（上节课留题 → 学生答 → 老师点评）——把「上一课真的学会了吗」变成显式关卡；
- 留题给下一课（宿主直改楼下会变，那从视图改楼下呢？）——用悬念缝合课与课。
非对话体文章同样可用：插问变成「 FAQ 小节」，留题变成「下一节的问题」。
12. 前后篇互链 + 伏笔
范文对照第 14 篇 bind mount（「一个是接一个目录，一个是叠多个目录」）、给第 10 篇多阶段构建埋伏笔。系列文章的价值在网状连接：每个概念标注「它从哪来、到哪去」，读者的知识才不成孤岛。
13. 老资料要标注「历史/兼容」语境
范文第 9 课整课在讲「老教程里的 AUFS 去哪了」：给出 AUFS↔OverlayFS 术语对照表，同时明说 aufs 驱动已在 Docker Engine 24.0 移除，还当场 grep aufs /proc/filesystems 验证本机没有——「命令没输出，本身就是答案」。
对 python:2.7-slim 这类历史教学配方，范文加框明示：语法照学，镜像别再用于生产。老内容不是不能写，是不能不标注。
四、事实纪律：三条不可协商
14. 先实验再写入，输出不可杜撰
范文的每一段输出（mountinfo 那行长输出、c--------- 0, 0 的挡板、Storage Driver: overlayfs）都是本机真实运行结果。「可适当精简，但不可杜撰」——删减不改变性质，编造就失去全部信用。实测中「命令没有输出」也是结果，照样写。
15. 版本核验写进文章
版本敏感的结论标注出处与核验时间。范文在文末注明「本机实测（2026-08-21）：内核 6.6.87.2、Docker Engine 29.1.3」——半年后的读者拿着不同版本对不上号时，这行字替文章免罪。
16. 官方文档是取材母本
写前核验官方文档是否当前版本（范文的参考资料首行就是 Docker 官方 Storage drivers 三个页面 + kernel.org 的 OverlayFS 权威定义）。过时 API 不得当「现行最佳」写。
五、收尾：三条手法锁住成果
17. 小结串成一条线
范文的小结不是罗列标题，而是把九课重组成因果链：「联合挂载 → 可写/只读 → CoW → whiteout → 容器即同款 → 教材草稿本 → 一步一层 → 缓存 → 驱动演进」。小结的质量标准：只读小结，能否复原全文的逻辑骨架。
18. 验证步骤 + 收题 + 清理现场
- 验证步骤：给读者一条自己能跑的命令（「拿手头任意镜像跑
docker history，一行一层」）——读过的知识只有跑过才算数； - 收题：开篇/中途留的题，文末必须收（范文第 8 课的缓存排序题在小结里收尾）；
- 清理现场：
umount、docker rm收尾命令，实验目录保留可重做。留下可复现的世界，是操作手册的礼貌。
六、四种「读起来难受」的反模式
以下四种病灶，每一条都来自真实反馈。写作时逐条自查：
| # | 反模式 | 症状 | 药方 |
|---|---|---|---|
| 1 | 证据链先行 | 先贴大段输出/报错，再解释是什么意思 | 手法 7：预期在前，输出殿后 |
| 2 | 实验腔 | 「然后我执行了…接着输出显示…可以看到…」全篇流水账 | 手法 4/8：按概念组织，不按时间组织；每课一句话收口 |
| 3 | 200 字长单段 | 「怎么读这行输出」写成一大段，读者读到一半迷路 | 手法 6/7：拆解表、逐行认读，一段只讲一层 |
| 4 | 回扣滥用 | 每段都「如前所述」「下面将会讲到」 | 手法 2：路线图只给一次；段内自洽，靠结构不靠口头铺垫 |
一句话诊断：反模式 1、2 是「按作者顺序写」，3、4 是「没有结构硬凑结构」——四条的解法都在上面十八条里。
七、可照抄的写作骨架
把十八条压成一张填空模板，动笔前照抄骨架、填内容：
frontmatter：title / shortTitle / order / date / category / tag / description（一句话说清本文解决什么）
┌ 开篇 ─ ① 写在前面：痛点 + 凭什么值得学
│ ② 路线图：① → ② → …（一条线）
│ ③ 环境 + 官方入口
├ 正文 ─ 每节一个概念，依次：
│ 已知引入 → 直觉/比喻 → 命令 + 拆解表
│ → 先说看哪 + 输出 → 一句话总结
│ →（易混点成块）（插问/留题）（前后篇互链）
├ 纪律 ─ 真实输出不杜撰 · 版本核验标注 · 老资料标「历史」
└ 收尾 ─ 小结串线 → 收题 → 验证步骤 → 清理现场 → 参考资料 + 实测注记发布前检查清单（逐项打勾）：
八、结语：规范是地板，不是天花板
十八条手法看起来多，本质只有一条：永远站在读者的认知顺序上写作，而不是自己的实验顺序上。问题驱动、输出殿后、一步不跳、一句话收口——全是这一条在不同位置的投影。
范文的路线图说「走到哪算哪」，规范也一样：不必每篇都十八条全中，但开篇三件套（痛点、路线图、环境）和事实纪律三条（真实、核验、标注）是地板——地板之下没有「风格自由」，只有「读不下去」。
一句话总结：按读者的顺序写，一步不跳；用真实输出说话，一字不编。
参考资料
- 解剖标本：《从零理解 Docker 镜像分层——两个目录叠出一个文件系统（师生对话实录）》——本文全部手法标注的原位出处（2026-08-21 发布，WSL2 实测）
- 反模式清单来源：2026-08-17 Linux 基础系列（bind mount 篇）迭代中的写作反馈——「为什么写出来的文章读起来那么难受」
- 本博客全局写作约定：
~/.claude/CLAUDE.md《博客写作通用规范》（问题驱动 / 四问结构 / 循序渐进 / 先实验再写入 / 最新资料 / 模块内排序）