文档写了没人看，直到我把它挪到报错信息里

我们组的 wiki 里有一篇《部署手册》，三千多字，写得很用心，目录、流程图、注意事项一应俱全。上线那年我挺得意的。后来有一次我随口问新来的同事，部署前要不要先看一下手册，他说：看啊，我一般直接搜关键词。

我问搜什么。他说搜报错。

那一刻我有点受打击，但想想也对。我自己也一样，没人会在顺利的时候去读文档，都是在卡住的时候才去翻，而卡住的时候手上只有一个报错信息。

后来我就不怎么写长文档了。

我把东西挪到了它该出现的地方

举个最小的例子。我们的构建脚本以前失败只会打一句 build failed，然后一大段堆栈。后来改成先判断最常见的三种情况，直接把结论打出来：

node_modules 缺失，先跑 pnpm i
Node 版本不对，当前 v18，需要 >=20
端口 3000 被占用，lsof -i:3000 看一下

写这三行的成本不到半小时，之后半年里，这个问题再没进过我的私聊。

同类的事还有配置。以前我们在文档里写「注意 DATABASE_URL 不要带引号」，没人看。现在启动时直接校验，带了引号就抛错，错误信息第一句就是那句话。粗暴，但有效。

不是文档没用，是位置不对

我现在的判断标准很土：如果一条知识只有在人主动去查的时候才有用，那它八成会被忘掉；如果它会自己跳出来，那才算真的落地了。

所以写文档之前我会先问一句：这个人会在什么场景下需要它。如果答案是报错的时候，那它就该出现在错误信息里；如果答案是改代码的时候，那它就该是注释或者类型定义；如果答案是交接的时候，那才轮到 wiki。

大部分知识其实都不属于 wiki。

当然也有例外。流程类的东西没法塞进报错里，比如发版前要找谁确认，这种还是得写下来，只是我会尽量把它压缩成一页能看完的东西。

三千字的手册我删到了两百字，剩下那些，都散落在代码里了。