我们为什么停止使用 Notion 编写产品文档

我过去把一切都放在 Notion 里。内部手册、产品规格、面向客户的常见问题、API 示例、值班轮换操作手册、更新日志，还有那份没人读过的半成品入门指南。一个工作区、一个搜索框、一套权限。大约十八个月来，一切感觉都很棒。

后来，我们尝试为文档增加流量。接着，我们又尝试添加第二种语言。然后，一位客户问，为什么他们正在阅读的页面比 API 落后三个版本。等我把所有内容从 Notion 迁移出去时，我已经列出了一份错误清单，多希望有人在第一天就交给我。

这就是那份清单。这不是一篇抨击文章——对于其设计用途而言，Notion 确实是一款很好的产品。这篇文章讨论的是“优秀的 wiki”不再等于“优秀的文档”的那个具体时刻，以及如何在你拥有 400 个页面、销售团队又需要文档真正获得排名之前，察觉到这一时刻。

Notion 仍然胜在哪里？#

先不谈抱怨，先说句实话。

Notion 是我用过的最适合协作思考的工具。战略文档、会议记录、正在起草的 RFC、四个人在评论中争论不休的产品规格——Notion 是正确的选择。块模型、数据库视图、内联数据库、关联提及，以及任何非技术人员都可以编辑而不会破坏任何内容——这些优势都是真实存在的，而且很难复制。

如果你的文档完全存在于公司内部，从来不需要在 Google 上争夺陌生人的注意力，那么 Notion 就够用了。如果你的受众是四十个都拥有 Notion 登录信息的人，那么这篇文章与你无关。关闭标签页，去写点有用的东西吧。

本文接下来的内容，讨论的是文档离开公司内部的那一刻。

1. 搜索是两个不同的问题，而 Notion 只解决了其中一个#

Notion 的内部搜索非常出色。Cmd+K，可以在标题中进行模糊匹配，直接跳转到页面。这正是工程师所关注的搜索，而 Notion 将它做得很好。

客户所关心的搜索发生在 Google、ChatGPT 和 Perplexity 上。而在这种搜索中，Notion 默认并不友好。页面通过 JavaScript 加载，在 React 完成 hydration 之前，HTML 基本上是空的；内部链接会经过 notion.so/<hash> 重定向，标题通常使用非语义化标记渲染，而 URL 看起来像 notion.site/Getting-Started-9f8a3b2c1d4e。Google 可以抓取它，但与同样内容以纯 Markdown 形式发布在普通域名上的情况相比，其 SEO 效果始终更差。

有一次，一个内容客观上比我们更差的竞争对手，仅仅因为他们使用 Markdown 并发布了站点地图，就超过了我们的排名。那一刻我真正意识到了其中的教训。面向客户的文档是 SEO 的一块阵地，需要以相应的方式对待它。Wiki 不是 SEO 的阵地。

2. 并非版本控制的版本控制#

Notion 有页面历史记录，但它不是 Git。这两者的差异比我预想的更重要。

我无法在代码审查中对比文档的两个版本。我无法问“v1.4 和 v1.5 之间 auth 部分改了什么？”并得到一个清晰的答案。我无法将文档变更与其所记录的代码变更放在同一个拉取请求中，因此文档总是稍有滞后。我无法要求初级工程师在发布 API 的同一个 PR 中更新 API 参考文档，因为文档位于另一个系统中，拥有不同的权限和不同的思维模型。

结果就是文档漂移。代码周一发布，文档周四更新，而周三客户读到了旧版本并提交了支持工单。每次发布都如此累积。解决办法不是“提醒人们更新 Notion”。解决办法是将文档放在代码旁边，这样“代码已发布但文档没有更新”就会成为差异工具能够向你发出警告的问题。

当我把文档放进一个带有 PR 模板的仓库后，文档更新开始成为完成定义的一部分，而不再是事后补充。这一项工作流的改变，对保持文档新鲜度所起的作用胜过任何工具。

3. 多语言不是一项功能，而是一种架构#

我们曾经尝试将 Notion 文档国际化。计划本身很合理：复制工作区、进行翻译，再通过语言切换器相互链接。但不到一个月就无法维护了。

多语言文档的真正成本不在于翻译，而在于语言之间的耦合。当英文版本发生变化时，所有翻译都会过时，而你需要一个能够识别这一点的系统。你需要：

• 一个规范源，以便译者知道自己翻译的是哪个版本。
• 一种在源文档发生变化时标记翻译已过时的方法。
• hreflang 标签，以便 Google 知道西班牙语页面是英文页面的西班牙语版本，而不是重复页面。
• 每种语言对应一个 URL，并使用可预测的路径（/es/getting-started、/de/getting-started）。
• 一种发布部分翻译的方法——某些页面提供五种语言，其他页面提供两种语言——同时不破坏导航。

Notion 完全不支持这些功能。最终你会得到五个互不相连的工作区，以及一个用于跟踪不同步内容的 Google 表格。Google 表格大约能坚持三周，然后所有人都会放弃。

如果你计划以一种以上的语言发布文档，就不要从 Notion 开始。迁移成本会随页面数量线性增长，而痛苦程度会超线性增长。

4. AI 爬虫无法读取你的 wiki#

这是一个新问题，也是我低估了的问题。

到 2026 年，相当一部分“X 是如何工作的”问题根本不会到达你的网站。用户会询问 ChatGPT、Claude 或 Perplexity，而答案则综合自这些模型能够看到的内容。Mintlify 对其托管的文档网站进行了为期 30 天的流量测量——请求量约为 7.9 亿次——并报告称，AI 编程代理占所有请求的45.3%，其中 Claude Code 占 25.2%，Cursor 占 18.0%（文档网站中的代理流量现状，发表于 2026 年 4 月 3 日）。其后续测量显示，2026 年 7 月代理流量占比达到 66%（2026 年年中报告，发表于 2026 年 7 月 29 日）。这反映的是一家供应商的代理群体，而不是整个 Web，但它是目前公开发布的针对文档的代理流量测量中规模最大的一项。我们自己的数字较小，但趋势相同。

AI 爬虫要引用你的文档，就必须能够读取你的文档。这意味着干净的服务端渲染 HTML、语义化标题、一个 sitemap.xml，最好还有一个列出规范内容的 llms.txt，以及面向 robots.txt 中主要 AI 用户代理的 Allow。Notion 几乎无法提供其中任何一项。其 HTML 高度依赖 JavaScript，没有 llms.txt，而且 AI 爬虫的回答率从实证来看很低。

如果你希望被答案引擎引用，那么从爬虫的角度看，你的文档就需要像一个文档网站。它们不能看起来像是围绕数据库视图构建的 SPA。

5. 文档的性能预算非常严苛#

文档页面应该让人感觉瞬间打开。这不是风格偏好，而是转化率的关键因素。用户可能在凌晨两点调试问题，他们已经很沮丧了，加载时间的每一秒都可能让他们放弃，并转而提交工单。

用 Lighthouse 测试一个由 Notion 发布的页面。结果并不理想。在真实的蜂窝网络连接下，最大内容绘制通常需要 3–5 秒，累积布局偏移很明显，因为 React 树会分批进行 hydration；总阻塞时间也很长，因为需要解析大量 JavaScript。

对于没人关心的内部 wiki，这无所谓。但对于面向客户、必须与用户打开的上千个其他标签页竞争的文档来说，这一点非常重要。我们将文档页面迁移到静态渲染的 Markdown 后，发现跳出率有了明显下降。这就是那种一旦见过，就再也无法忽视的数据。

6. 锁定效应确实存在，而且会不断加剧#

Notion 提供导出功能。我使用过它。导出的结果是一个包含 HTML 或 Markdown 文件的文件夹，文件名被弄得一团糟，内部链接损坏并指向 notion.so URL，嵌入式数据库被扁平化成难以阅读的表格，图片引用则指向会过期的签名 S3 URL。导出 400 个页面，然后修复导出结果，需要整整一周的工作。

锁定效应与是否存在导出按钮无关。关键在于，导出的数据是否具有足够好的结构，能够在没有迁移工具的情况下于其他工具中使用。以此标准来看，Notion 的导出能力很弱。你使用得越久，积累的页面越多，迁移成本就越高。只有当你试图离开时，才会意识到这一点。

Git 仓库中的 Markdown 则具有相反的特性。“导出”就是 git clone。你可以将该目录移动到任何其他静态网站生成器、任何其他文档平台，或者直接将其作为原始文件发布。这种可移植性是文档系统最被低估的特性。直到你真正需要它的那一天，你才会感受到它的价值；而到了那时，它将价值连城。

7. 权限、草稿，以及 wiki 与文档的划分#

最根本的问题在于，wiki 和文档是两种不同的产品，只是在编辑器中看起来相同。

wiki 是为我们准备的。它包含草稿、未完成的页面、仅供内部查看的部分、两位团队负责人在评论中意见不一致的页面、绝不应公开的操作手册，以及一个实际上只是用来遗忘内容的“存档”文件夹。权限模型之所以细致，是因为受众也有细分。

文档是为他们准备的。只有一个已发布版本，没有半成品状态，读者看不到草稿，公共 URL 中也不会显示评论线程。草稿存在于拉取请求中，而不是生产目录中。权限模型是二元的——已发布或未发布——因为受众是整个互联网。

Notion 是为前一种工作打造的，并通过修补来应对后一种工作。最终，你会得到一个混合了内部员工手册页面和面向客户的 API 文档的工作区，它们位于同一棵目录树中，而一次配置错误就会让错误的页面公开。我在三家公司见过这种情况，而且自己也差点犯下同样的错误。

“wiki”和“文档”之间的边界值得以实体形式划分。不同的系统、不同的仓库、不同的审查流程、不同的域名。

我们改用什么？#

对于需要评论、观点、草稿和内联数据库的内部事务——战略文档、RFC、会议记录、员工手册——Notion 仍然是合适的工具。我们并没有停止使用 Notion，只是不再把它用于错误的场景。

对于面向客户的文档，文档存放在 git 仓库中，以 Markdown 编写，通过拉取请求进行审阅，并作为静态网站发布。这个设置特意保持简单。文档与代码放在一起，因此会在同一个 PR 中更新。git 历史就是版本历史。仓库就是导出文件。CI 会运行链接检查。发布的网站采用服务器端渲染，包含适当的标题、站点地图、一个 llms.txt，并且每种语言对应一个 URL。

无论你使用 Docsbook、Docusaurus、Mintlify、VitePress，还是用 eleventy 自行搭建，这其实都没有看起来那么重要。更重要的是之前的那个决定：这些文档是给团队看的，还是给全世界看的？如果是给全世界看的，就把它们从 wiki 中移出来，放进一个把文档当作产品来对待的系统中。

我们构建 Docsbook，是因为我们希望让“Markdown 的 git 仓库”在五秒内变成“具备 SEO、AI 聊天、十五种语言和分析功能的已发布文档网站”——而无需单独的 CI 步骤或 docusaurus.config.js。这是这个故事中我们有产品可销售的版本，也是我们实际走过的诚实道路。我们先尝试了 Notion，之后尝试了 Docusaurus。最终，我们编写了 Docsbook，因为我们想要 Notion 的简洁性，以及真正文档网站的工程属性，而当时没有其他人构建出这样的产品。

唯一值得坚持的原则#

如果你的文档需要被公司以外的人找到，那么它们就是一种 SEO 和 AI 可发现性产品。请以对待产品的方式对待它们。将它们纳入源代码管理，将其渲染为 HTML，为每种语言提供真实的 URL，并确保爬虫无需运行 JavaScript 就能读取它们。

Wiki 是为已经身处其中的人准备的。文档则是为仍在外面、向内观望的人准备的。你只有一次机会留下第一印象，而这通常发生在凌晨两点，读者拿着手机、心情烦躁的时候。请为这样的读者构建文档，而不是为编写文档的那场会议。

这就是经验。其他一切都只是实现细节。

免费开始使用 — 无需信用卡

后续步骤#

• 如何从 GitHub 仓库托管文档 — 摆脱 wiki 的三条路径
• 文档 SEO 指南 — 第 1 节完整描述的搜索问题
• 多语言文档 SEO — 第 3 节提到的架构要点
• 如何让 ChatGPT 引用你的文档 — 第 4 节提到的爬虫问题