笔记和教程的区别

翻自己两年前的笔记，经常遇到这种段落：

这里要用 --cap-add=SYS_ADMIN，不然会报错。

然后就没有了。报什么错？为什么需要这个权限？换台机器还行不行？

我自己能看懂，因为写的时候我脑子里有完整上下文。但三个月后的我，已经变成了「别人」。

这两年我慢慢摸清楚，笔记变成能给别人看的教程，差的不是内容质量，是三样东西。

一、缺上下文

笔记默认「我知道自己在说什么」。教程必须假设读者什么都不知道。

那行 --cap-add=SYS_ADMIN，补上上下文之后是这样：

容器默认以受限权限运行。如果容器内需要挂载文件系统（比如跑一个 FUSE 程序）， 内核会拒绝这个操作，报 operation not permitted。 --cap-add=SYS_ADMIN 把 CAP_SYS_ADMIN 这个 capability 加回给容器。 注意这是很大的权限，接近 root，只在你信任这个镜像时用。

多出来的这几句，才是别人真正需要的东西。

二、缺推导过程

笔记只记结论，因为推导过程当时在脑子里。

但结论是最容易过时的东西 —— 版本一升级，--cap-add 可能就换成别的写法了。 推导过程不会过时，它告诉你这个结论是为什么成立的，因此结论失效时你知道该往哪找替代方案。

所以教程里我尽量写「因为 A 所以 B」，而不是直接给 B。

三、缺可复现的步骤

笔记里写「先装个依赖」，教程里必须写清楚是哪个版本、用什么命令装。

# 不是这样
apt install docker

# 而是这样
apt install -y docker.io
systemctl enable --now docker
docker --version   # 期望输出：Docker version 24.x

给出期望输出特别重要。读者跑到这一步发现输出不一样，就知道自己走岔了， 而不是带着错误继续往下跑。

那笔记还有价值吗

有，但价值不一样。

笔记的价值是当时的我写给当时的我，它的作用是记录「我做过这件事、结论是什么」。 它的读者只有一个，而且那个读者当时就在现场。

教程的价值是跨越时间的传递。它必须能在没有我在场的情况下独立成立。

所以现在我的做法是分开：

• 随手记的东西放本地笔记软件，不打算给别人看，怎么省事怎么写
• 一个主题想清楚了、验证过两遍以上，才整理成教程发布

判断标准很简单：如果我不能在半年后只看这篇文字就把它重做一遍，那它就还只是笔记。

一个副作用

把笔记整理成教程之后，我发现自己对技术的理解变了。

写笔记时我是在记录「怎么用」，整理教程时被迫回答「为什么是这样」。 好几个我以为自己懂的地方，在试图向别人解释的时候才发现是空的。

这可能才是整理教程最大的收益 —— 不是为了读者，是为了确认自己真的懂了。