Difyのドキュメントエンジニアリング実践：AI時代に向けたナレッジシステムをどう作るか？
GitBookからMintlifyへの移行の全過程：LLM向けのナレッジサービス、フレームワーク調査、そして画像・構文・リンクという三種類の移行課題。
このページの内容
ドキュメントがプロダクトの一部であるなら、読者にはどのような読書体験を提供したいでしょうか。そして、どこにでも存在する新しい読者であるLLMに対して、ドキュメントはどんな姿勢で向き合うべきでしょうか。
みなさん、こんにちは。Dify でテクニカルドキュメントエンジニアを務めている Allen です。
2025年4月から、私はDifyのヘルプドキュメントのフレームワークを、GitBookからMintlifyへ全面的に移行するプロジェクトを主導し、完了させました。フレームワークの調査と選定、デモでの実機検証、スタイルの互換性、リンクの再構築、そして最終的なリリースまでの全過程を担当しました。これは単なる技術スタックの置き換えではなく、AI時代のコンテンツサービスのためのインフラの再構築でした。
移行前後の比較です。
旧ドキュメント（Powered by GitBook）
現在のドキュメント（Powered by Mintlify）
#AI時代のナレッジサービス
この取り組みに価値があるかどうかは、AIの読書習慣に合わせた文書セットを、あえて専用に用意する覚悟があるかどうかにかかっています。AI時代のナレッジ体系では、情報をどのように再編成すべきでしょうか。
AIの革命が起きる以前、あらゆるソフトウェアのドキュメントは人間のために設計されていました。レイアウトは美しく目を引くものであり、読みやすさが求められました。情報は階層化され、段階的に深まっていく必要がありました。SEOを脇に置いたとしても、人間向けのドキュメントは一般に、洗練されたデザインと明快なレイアウトを求められます。しかしLLMにとっては、そうした外見はすべて表面的なものにすぎません。LLMが必要としているのは、十分な長さのコンテキストです。凝ったレイアウトは要らず、内容が充実し詳細であることが大切なのです。
#時代ごとの情報検索の経路
従来の検索：遭遇した問題を入力する／製品名と問題のキーワードを入力する → 検索エンジンが上位にランクされたコンテンツを選ぶ → 適切な解決策が推薦される。
ユーザーの行動は、次の三つの経路に抽象化できます。
- 検索エンジンでコンテンツを探す
- ドキュメントの階層構造を閲覧する
- ドキュメント内の検索機能を使う
Stripeのドキュメントは、この経路を極限まで突き詰めています。チーム内のどの役割のユーザーも、それぞれドキュメントの中から必要な情報をすばやく見つけられます。ログイン済みのユーザーに対しては、チームごとに専用のテストコードを自動生成することさえあります。
LLMとの対話の時代では、問題解決の経路は次のように変わります。LLMに質問する → LLMが推奨する解決策を提示する → ユーザーが追加の質問やフィードバックを返す → LLMが詳細なステップバイステップの説明を提供する。ユーザーはいくつものセクションを閲覧したり、特定のページを検索したりする必要がありません。代わりに、LLMに即座の答えを求めるのです。
#LLMがもたらした変化
大規模言語モデルはSEOを変えつつあり、生成エンジン最適化（GEO）を生み出しています。ある研究では、LLMからの検索トラフィックは、2024年の全検索量の0.25%から、2025年末には10%へと急上昇すると予測されています。
研究リンク：AI SEO Study 2024
製品の利用を軸に設計されたあらゆるテクニカルドキュメントにとって、この流れは、顧客が情報を見つけ、最終的に製品で成功する方法を覆すことになるでしょう。テクニカルドキュメントエンジニアが生み出すコンテンツは、LLMが対象製品を理解する度合いに大きく影響します。
LLMにとって本当に使いやすいものにするには、テクニカルドキュメントには一つの重要な機能が必要です。llms.txt の自動生成です。llms.txt は純粋なMarkdownファイルで、最も重要な内容を簡潔にまとめ、LLMが読みやすい形で構成されています。HTMLやJavaScript、広告の雑然としたノイズは含みません。
今回のアップグレード全体の目標は、こうして定められました。
- LLMのクロールに優しい。 GEOに全面的に対応し、AIの自然言語による回答に製品が登場しやすくなります。
- APIドキュメントを備える。 完全で明確であり、オンラインでのデバッグとサンプル呼び出しをサポートします。
- AIによるドキュメント対話をサポートする。 自然言語で質問し、インターフェースの説明、統合ガイド、トラブルシューティングの助言を得られます。
#計画してから動く
#1. 問題を明確にし、GitBookを廃止する
これまでDifyのドキュメントはGitBookを使っていました。GitBookは最初のバージョンのドキュメントとプロジェクト全体のオープンソース化を見届けてきましたが、次第に多くの根本的な問題が表面化していました。ハイパーリンクが固まる、複数人で編集すると画面が真っ白になる、目次の階層が縦に長すぎる、APIドキュメントの描画に異常が出る、公開済みのコンテンツが自動的に書き換えられる、そして完全に機能するローカルプレビューのアドレスがない、といった問題です。
根本的な原因は、このプラットフォームがプログラミング能力を持たないビジネス担当者向けに設計されており、ほとんどの操作がグラフィカルなインターフェースに依存していることにあります。IDEを通じてコードを取得し、ドキュメントを管理することはできますが、ローカル環境では描画結果をプレビューできません。GitBookは、Docs as Codeの製品ではないのです。エディタ上の描画と最終的に公開されるページが一致しないことも、しばしばありました。
チームは新しい方向性を明確にしており、最初の決定は、GitBookの使用を停止し、代わりを探すことでした。
#2. 目標を中心に、十分に調査する
ドキュメントはプロダクトの一部です。当時、Difyのドキュメントは600本を超えており、内部の入れ子の参照も多くありました。新しいフレームワークの寿命は、少なくとも三年以上を想定して設計すべきです。私は主流のテクニカルドキュメント・フレームワークを調査し、実際に試しました。詳しい比較表は次にあります：Difyドキュメント再構築メモ。
じっくり試用した結果、候補はMintlifyとDocusaurusに絞られました。
- Mintlifyは、ビジュアルとAPIドキュメントの自動生成の面で成熟しています。デフォルトのスタイルで、ほとんどの表示ニーズを満たせます。
- Docusaurusはオープンソースで拡張性がありますが、APIドキュメントの統合には追加のツールが必要で、Reactのスキルを持つチームに向いています。
後のメンテナンス、すぐに使えること、そしてチームのAI機能への投資を総合的に考慮し、私はMintlifyを選びました。
#実行
#1. フレームワークに慣れ、小さく反復する
フレームワークが決まったあと、まずはデモを作り、何度も話し合いを重ねて、少しずつチームの賛同を得ていきました。Mintlifyは従来の .md ではなく .mdx を使います。AI技術が急速に発展する状況では、コンテンツの形式変換はもはや障壁ではありません。それよりも重視すべきは、構造の拡張性と、スマートなツールとの融合の可能性です。
#2. 問題を明確にし、一つずつ攻略する
#問題1：画像処理の仕組みが不明確
元の体制には、統一された画像ホスティングがありませんでした。リポジトリのサイズが膨らみ、命名やパスにも規則がありませんでした。GitBookは画像を非公開でホストし、CDNも使っていなかったため、地域をまたぐ読み込みが不安定でした。
解決策：PicoとS3を使って自前の画像ホストを構築し、自動命名と保管を実現しました。画像をメインのリポジトリから切り離し、CDNで高速化しました。過去のローカル画像は、スクリプトで一括アップロードしました。
#問題2：構文の形式が統一されていない
GitBookのhint構文は直感的でなく、フロントエンドの予約記号と衝突しやすいものでした。比較は次のとおりです。
GitBook：
{% hint style="info" %}
The name Dify comes from Do It For You.
{% endhint %}Mintlify：
<Info>
The name Dify comes from Do It For You.
</Info>
解決策：よく使われるスタイルの対応関係をプロンプトに組み込み、Difyのチャットアプリを使って、GitBookの構文をMintlifyのMDXに自動変換しました。
#問題3：ハイパーリンクの参照構造が複雑
完全なオンラインのリンクもあれば、リポジトリ内の相対パスもありました。Pythonスクリプトで全リンクを特定し、推奨される置換パスをハイライトしてから、人の目による確認を経て、一括で置き換えました。
#3. 最終的なリリース：スムーズな移行を確実に
リリース前に、ページごとにリダイレクトを確認しました。GitBookとMintlifyではURLの構造が異なるため、リダイレクトを軽視することはできません。評価の結果、A/Bのカナリアリリースは行わず、安定性、アクセシビリティ、そしてユーザー体験に影響しないことという核心の目標に絞りました。リリース当日は切り替えがスムーズに完了し、ほとんどのユーザーは気づきませんでした。その後、DevRelの同僚の協力を得てAPIドキュメントを公開し、各ページの下部にフィードバック入口を埋め込みました。
#ドキュメントの背後にあるもの：読書体験の全体掌握
この移行は、技術的な挑戦であっただけでなく、役割に対する認識そのものを作り直すものでもありました。Mintlifyはまもなく、ドキュメントMCPに対応しました。関連ガイド：Difyのドキュメントで AI と対話する。
Mintlifyも公式に、内蔵のAI対話機能をリリースしました。
Mintlifyは現在、Claude、Cursor、Perplexityといった主要なAIベンダーにとって、第一に選ばれるドキュメントフレームワークになっています。
テクニカルドキュメントエンジニアにできることは、良いドキュメントを書くことにとどまりません。その役割は、むしろドキュメント製品の責任者に近いものであるべきです。信頼できるコンテンツ、スムーズな閲覧体験、そして持続可能な利用の道筋を提供することです。