tdr · essay

论文档之死

关于工程组织里那个无人愿读、也无人愿写、却仍然每周新生的文体 — 文档。一份冗长的辩护词。

文档死了。它死于会议纪要，死于 Confluence，死于"@everyone 请看 RFC"的提醒，死于工程师"晚点写"的承诺与产品经理"先做再说"的默契。它死于我们将注意力外包给搜索引擎与大模型之后 — 当一切问题都可以问，谁还会停下来读？这不是悼词。这只是一份盘点：文档死前，长什么样；死后，留下了什么。

我们写文档不是为了让人看见我们写过什么，而是为了让六个月之后回到现场的那个人 — 也许是别人，也许是自己 — 不必从头猜起。

什么算是文档

在动笔之前，我们先约定一个共同的定义。文档不是任何写在屏幕上的字 — Slack 不是，Jira 不是，PR description 不是。文档是一个特殊的文体：它假设读者不在事件现场，因此必须自带上下文；它假设读者会在未来某个时刻才打开，因此必须经得起时间。当一段文字同时不满足这两条，它属于沟通，不属于文档。

这条界限解释了为什么"我们的文档很多"和"我们没有文档"可以同时成立。RFC、设计稿、上线公告 — 这些文档通常长得像文档，但一旦剥掉模板，剩下的往往只是会议结论加几张白板照片。它们假定读者就在身边，假定时间静止。它们是当下的，不是未来的。

三种相邻文体

把文档从相邻文体里区分出来，有助于看清它真正的边界：

三者并非高低关系，而是分工 — 把工程文档当成会议纪要的扩写，是当代组织文档质量崩塌的最常见路径。

关于"写"的三个误解

谈"写"之前，先清理那些被反复念诵但从未被验证的口号。这些口号不只是错的，它们是有害的 — 它们让作者以为自己在写文档，实际上只是把模板填了一遍。

好文档应当包含所有细节，以便日后查阅。 好文档刻意省略 — 它假设读者具备某种基线能力，并在这个基线之上构建。穷尽细节的文档无人能读完；什么都写的文档等于什么都没写。 结构清晰、模板规整 = 高质量文档。 结构是骨架，叙事是肌肉。一份只有骨架、没有叙事的文档读起来像验尸报告 — 信息齐全，毫无温度，毫无判断。把模板填完只是起点，不是终点。 文档是工程师写完代码之后的"补作业"。 真正的文档在动手之前 — 当你写不清楚你要做什么，你就还没准备好开始做。"先做后写"通常意味着"做完不写"，因为做完之后你再也没有动力回到那个状态里去解释自己。

论证：为什么我们仍要写

面对前述三个误解，最常见的反应不是修正，而是放弃。"既然全写出来没人看、模板化没用、写在前面又写不出来，那干脆就别写了。" 这是一种诱人的退路。本节给出三条反驳。

它是组织记忆的唯一稳定载体。Slack 历史会过期、Jira 会迁移、人会离职 — 唯有归档良好的文档，能在五年后被一个素不相识的新人独自读懂。 它是判断能力的训练场。把一个复杂决策写到能让别人理解的程度，几乎必然暴露出原本以为"已经想清楚"的盲区。写不出来 = 没想清楚。 它是协作的边界条件。当问题足够大、涉及人足够多时，口头沟通的失真率随人数指数上升；只有书面材料能让一个十人组织对齐到同一个版本。 它是对未来自己的债权。今天写下的一段说明，是为半年后的自己省下一小时拼凑上下文的时间 — 这是一种确定性极高的复利。

这四条都不是新论点。但它们值得在每次决定"这次先不写了"之前被重新念一遍。

两种风格的折中

我们见过的最好的工程文档，几乎都在两个极端之间做了某种折中 — 一端是 RFC 的严谨、可追溯、结构化；另一端是随笔的叙事、判断、个人化。下表是一份非常粗暴的对照，仅供启发：

这张表的真正用法不是去选一边，而是意识到自己在选。一份装作 RFC 的随笔，和一份偷偷想当随笔的 RFC，是工程组织里最常见的两种烂文档。

论文档之美

本节是这篇文章最不像工程文章的一节 — 谈论审美。

排版的传统是慢的。一本书的页面比例、行长、字距、引号悬挂、首字下沉、章节序号 — 这些细节经过几百年的优胜劣汰沉淀下来，每一项都解决了一个具体的阅读问题。我们今天把工程文档塞进 Notion 默认模板里，丢掉的不是装饰，而是这些被验证过的"如何让人愿意继续读下去"的智慧。

这不是怀旧。这是承认一个朴素事实：没人会读他不愿意读的东西。当你的 RFC 长得像 stack overflow，你的同事就会用读 stack overflow 的方式扫两眼。当它长得像一本书，他可能会真的从头读到尾 — 哪怕只为了对得起那个排版。

文档之死，从哪里开始

每一份死去的文档，回溯起来，都死于一个具体的瞬间。下面这条时间线不是真实事件，是一个虚构的合成 — 但每一格，你或许都在自己的某份文档里见过它的影子。

作者带着冲动开始写，前三段质量极高 — 这是文档生命中最好的一刻。 作者发现要解释清楚需要先讲十件其他事。开始迟疑。 「等评审意见再细化」— 一句几乎一定让文档死亡的话。 三个人提了七条相互冲突的意见。作者收下了所有，并失去了最初的判断。 从此再没人打开过它。它存在，但不被读 — 这是比删除更彻底的死亡。

有没有救？有。但救法不在文档本身，而在写作的人 — 在他是否愿意把"评审是为了打磨我的判断"理解为"评审是为了用别人的判断替换我的判断"。

四种危险

把"写不下去"具体化，大致可以归为四类风险。风险矩阵 — 严重度乘以可能性 — 在写作里同样适用：

结语

这篇文章本身是一份文档。它谈论了文档的边界、文档的误区、文档的美学、文档的死亡。如果它最终被读完一次 — 哪怕只有一次 — 它就胜过了我见过的绝大多数 RFC。

下次你坐下来准备写一份新的文档时，先做一件事：把你脑子里关于"应该怎么写"的所有念头放下，问自己一个朴素的问题 — 半年后那个不在场的人，需要先知道什么。从那个答案开始写。

剩下的，会自己找到位置。

由 talon-doc-runtime 渲染 · archetype: editorial-longform · 深色 浅色 自动