Dify 技术文档工程实践:如何构建面向 AI 时代的知识系统?
如果文档是产品的一部分,你希望获得怎样的阅读体验?文档又应该以何种姿态面向新读者——即无所不在的 LLM?
大家好,我是 Allen,来自 dify 的技术文档工程师。
从 2025 年 4 月开始,我主导并完成了 Dify 帮助文档框架的一次全量迁移工程——从 Gitbook 到 Mintlify。完成从调研选型、Demo 实测、样式兼容、链接重构到最终上线的全过程。这不只是技术栈的替换,更是一次面向 AI 时代内容服务的基础设施重构。
以下是迁移前后对比。乍一看好像没啥区别,这一切值得吗?
AI 时代下的知识服务
要回答这件事是否值得,取决于你是否愿意专门为 AI 提供一套适应它们阅读习惯的文档。如果单独抛开迁移这件事本身而言,而是升华到行为背后的动机,则必须回答关键问题:面向 AI 时代的内容的知识体系,应该如何重新组织信息?
AI 革命爆发以前,所有的软件文档皆是为人类设计的。排版布局需要考虑美观吸睛、阅读友好。信息要分层递进,逐步深入。拿常规的 SEO 而言,想要让搜索引擎精准的在茫茫内容中找到你的内容,你需要在 HTML、元数据或内容地图上下足功夫。
哪怕抛开 SEO 要素,面向人类的文档通常要求设计简洁优美,布局清晰;而对于 LLM 来说,外在都是表象,它需要的是足够长的上下文。不求精巧的排版,但求内容的充分详实。
不同时代下的信息检索路径
我们不妨假想一个场景,用户在什么情况下需要文档?很显然,TA 遇到了问题。过往的信息检索路径可能是:
传统检索:
输入遇到的问题 / 输入产品名称 + 问题关键词 → 由搜索引擎挑选排名权重靠前的网站中的内容 → 推荐合适的解决方案
用户行为可被抽象为三种路径:
- 通过搜索引擎查找内容
- 浏览文档层次结构
- 使用文档搜索功能
Stripe 文档 (https://docs.stripe.com/)可谓是在这条路上达成了登峰造极般的程度。团内任意角色的用户,都可以各自在文档内快速找到所需信息。文档甚至会为已登录的用户,自动生成专属于用户团队的测试代码。
而在 LLM 互动时代,问题的解决路径变为了:
询问 LLM → 由 LLM 给出推荐方案 → 用户提问反馈 → LLM 给出详细的手把手教学
用户无需浏览各个部分或搜索特定页面,而是转向 LLM 寻求即时答案,而不必自行将来自不同页面的信息拼凑在一起来获取结论。
LLM 所带来的改变
毫无疑问,大型语言模型 (LLM) 正在改变搜索引擎优化 (SEO)。这同时还催生出了一个新领域:生成式引擎优化 (GEO)。有研究预测,来自 LLM 的搜索流量将从 2024 年占所有搜索量的 0.25% 飙升至 2025 年底的 10%。
研究链接:AI SEO Study 2024(https://previsible.io/seo-strategy/ai-seo-study-2024/)
对于一切围绕产品的使用而设计的技术文档而言,这样的趋势将颠覆客户查找信息并最终通过产品获得成功的方式。
LLM 会优先考虑提供什么样的内容?当然是它最了解和熟悉的方法,亦或是互联网上大家通常采取的策略。
它俨然已成为最大的内容消费者,疯狂地吞噬互联网上的一切内容。甚至随着 Agent 工具的出现,它终将长出手和脚,基于它所掌握的信息,代替人类完成对物理世界的交互。
而在这场变革中,技术文档工程师(Technical Writer)所输出的内容,将显著影响 LLM 对于目标产品的掌握。
若要真正做到对 LLM 友好,技术文档需具备一个关键能力:自动生成 llm.txt 文件。
llms.txt 是一个纯 Markdown 文件,它以简洁的方式概括了您最重要的内容,并以易于 LLM 阅读的方式组织结构,避免了 HTML、JavaScript 或广告的杂乱。
除了 LLM 阅读友好,作为一个开发者工具文档,本就应该确保开发者用户的交互体验。最常见的功能便是 API 文档,最好支持所见即所得的在线调试体验。至此,整套升级行动所要实现的目标也就此确立:
- LLM 爬取友好
全面兼容 GMO,让产品或解决方案更容易出现在 AI 的自然语言回答中,从搜索引擎到智能助手,全面提升可见性。
- 具备 API 文档
提供完整且清晰的 API 文档,支持在线调试与示例调用,帮助开发者快速理解接入方式,显著提升人类程序员的开发效率与使用意愿。
- 支持 AI 文档对话
支持基于文档的 AI 对话,让开发者或用户可以通过自然语言提问的方式获取接口使用说明、集成指南或排障建议,减少重复咨询,提升支持效率与产品好感度。
先谋而后动
1. 明确问题,弃用 Gitbook
此前 Dify 文档使用的框架为 Gitbook,它见证了第一版的文档和整个项目的开源。但随着时间的演进,它逐渐暴露出了非常多底层的问题。来看看我自接手文档写作以来所积攒的问题列表吧(否则我也不会这么想要换掉它):
根本原因在于该平台的产品定位面向不具备编程能力的业务人员,旨在提供技术写作与协作能力,因此大部分操作依赖图形化界面完成。尽管平台支持通过 IDE 拉取代码进行文档维护,但由于本地环境无法预览渲染效果,使用体验受到较大限制。
Gitbook 并不是一个 Doc as Code 的产品。
此外,平台内置编辑器的渲染效果与最终发布页面存在明显差异,实际呈现效果与预期之间常出现落差,技术实现上的不一致性为使用者带来了诸多困扰。
在处理外部用户投稿内容时也面临类似问题:部分样式或渲染代码无法实现实时预览,上线结果往往无法预测,类似"开盲盒"的体验。考虑到当前团队已明确新的发展方向,首要决策即为停止使用 GitBook 平台,寻找新的替代。
2. 围绕目标,充分调研
我始终坚持这样一种观点:文档是产品的一部分。正因如此,任何对文档系统的重大调整,必须在充分思考与权衡之后再做决策,尤其是在迈向 AI 化转型的关键阶段。
据不完全统计,当时 Dify 的文档总量已超过 600 篇,且内部嵌套的引用链接繁多、结构复杂。如果将整个文档系统比作一座建筑,这座新"大楼"的设计寿命至少应为三年以上,甚至可能在较长时间内保持稳定。因此,新的文档框架不仅要延续既有的良好体验,还需具备良好的可维护性与未来可持续扩展的能力。
为此,我对市面上的主流技术文档框架进行了调研与实际使用,并整理成对比表格,供团队参考,也希望对有类似需求的朋友有所帮助。
如果微信表格渲染有异常,请在浏览器打开原文链接:https://docs.pflm.net/zh-hans/insights/dify-docs-restructure
| 内容展示 | |||||||
| 内容管理 | |||||||