Docsbook
概要

製品ドキュメントにNotionを使うのをやめた理由

以前は、何もかもNotionに入れていました。社内ハンドブック、製品仕様、顧客向けFAQ、APIの例、オンコールローテーションの手順書、変更履歴、誰も読まなかった作りかけのオンボーディングガイド。ワークスペースは1つ、検索ボックスも1つ、権限セットも1つ。約18か月間は、とても快適でした。

その後、ドキュメントへのトラフィックを増やそうとしました。次に、2つ目の言語を追加しようとしました。そしてある顧客から、読んでいるページの内容がAPIより3リリースも遅れているのはなぜかと尋ねられました。Notionからすべてを移行し終えた頃には、初日に誰かから渡してほしかったと思う失敗のリストができていました。

これはそのリストです。これはNotionを批判する記事ではありません。Notionは、想定された用途において本当に優れた製品です。これは、「優れたWiki」が「優れたドキュメント」ではなくなる具体的なタイミングと、400ページも作成し、ドキュメントが実際に検索上位に表示される必要がある営業チームを抱える前に、そのタイミングに気づく方法についての記事です。

Notionは今でもどこで優れているのか？#

不満を述べる前に、率直な話をしよう。

Notionは、私がこれまで使ってきた中で、共同で考えるための最高のツールだ。戦略文書、会議メモ、下書き中のRFC、4人がコメントで議論しているプロダクト仕様書――Notionが正解だ。ブロックモデル、データベースビュー、インラインデータベース、リンク付きメンション、技術に詳しくない人でも何も壊さずに編集できること――これらはすべて実在するNotionの強みであり、再現するのは難しい。

ドキュメントが完全に社内だけに存在し、Google上で見知らぬ人の注目を集める必要がないなら、Notionで問題ない。読者が全員Notionのログイン情報を持っている40人なら、この投稿はあなたには関係ない。タブを閉じて、何か役に立つものを書きに行こう。

この投稿の残りの部分では、ドキュメントが建物の外に出る瞬間について扱う。

1. 検索には2つの異なる問題があり、Notionはそのうち1つを解決する#

Notionの内部検索は優れています。Cmd+Kで、タイトルを横断したあいまい検索ができ、ページに直接移動できます。これはエンジニアが重視する検索であり、Notionはそれをうまく構築しました。

顧客が重視する検索は、Google、ChatGPT、Perplexity上にあります。そしてその検索に対して、Notionはデフォルトでは不向きです。ページはJavaScript経由で読み込まれ、ReactがハイドレーションするまでHTMLの大部分は空のままです。内部リンクはnotion.so/<hash>リダイレクトを経由し、見出しは非セマンティックなマークアップでレンダリングされることが多く、URLはnotion.site/Getting-Started-9f8a3b2c1d4eのように見えます。Googleはクロールできますが、通常のドメイン上で同じコンテンツをプレーンなMarkdownとして公開した場合と比べ、SEOの成果は一貫して悪くなります。

客観的には内容が劣る競合が、Markdownを書いてサイトマップを公開したという理由で私たちを上回ったとき、初めて私はその教訓を実感しました。顧客向けドキュメントはSEOの対象です。そのように扱う必要があります。WikiはSEOの対象ではありません。

2. バージョン管理ではないバージョン管理#

Notionにはページ履歴があります。しかし、gitではありません。その違いは、私が思っていた以上に重要です。

コードレビューでドキュメントの2つのバージョンを比較できません。「v1.4とv1.5の間で認証セクションに何が変更されたのか」と尋ねて、明確な答えを得ることもできません。ドキュメントが説明するコード変更と同じプルリクエストに、ドキュメントの変更を含めることもできないため、ドキュメントは常に少し遅れます。APIをリリースする同じPRの一部としてAPIリファレンスを更新するよう、若手エンジニアに依頼することもできません。ドキュメントは、異なる権限と異なるメンタルモデルを持つ別のシステムにあるからです。

その結果が、ドキュメントの乖離です。コードは月曜日にリリースされ、ドキュメントは木曜日に更新され、水曜日には顧客が古いバージョンを読んでサポートチケットを起票します。リリースのたびにこれが繰り返されます。解決策は「Notionを更新するよう人々に念押しする」ことではありません。解決策は、ドキュメントをコードの隣に置き、「コードはリリースされたのにドキュメントは更新されていない」という状態を、差分ツールが警告できるようにすることです。

PRテンプレートのあるリポジトリにドキュメントを置いてから、ドキュメントの更新は後回しではなく、完了の定義の一部になりました。このたった1つのワークフローの変更が、どのツールよりもドキュメントを最新に保つことに貢献しました。

3. 多言語対応は機能ではなく、アーキテクチャです#

私たちは以前、Notionのドキュメントを一度国際化しようとしました。計画は妥当なものでした。ワークスペースを複製し、翻訳し、言語切り替えからリンクするというものです。しかし1か月以内に保守不能になりました。

多言語ドキュメントの本当のコストは翻訳ではありません。それは言語間の結合です。英語版が変更されると、すべての翻訳が古くなり、それを把握するシステムが必要になります。必要なのは次のものです。

  • 翻訳者がどのバージョンを基に翻訳しているのかを把握できる、正規のソース。
  • ソースが更新されたときに、翻訳を「要更新」として示す方法。
  • Googleがスペイン語ページを重複ページではなく英語ページのスペイン語版として認識できるhreflangタグ。
  • 予測可能なパス（/es/getting-started、/de/getting-started）を持つ、言語ごとに1つのURL。
  • ナビゲーションを壊すことなく、一部のページは5言語、その他は2言語というように、翻訳の一部だけを公開する方法。

Notionには、これらが何もありません。最終的には、互いに接続されていない5つのワークスペースと、何が同期していないかを記録するGoogleスプレッドシートが残ります。Googleスプレッドシートは約3週間は機能しますが、その後は全員が諦めます。

複数の言語でドキュメントを提供する予定が少しでもあるなら、Notionから始めないでください。移行コストはページ数に比例して増加し、苦痛はそれ以上のペースで増大します。

4. AIクローラーはあなたのWikiを読めない#

これは新たに加わったものであり、私が過小評価していたものです。

2026年までには、「Xはどのように動作するのか」という質問のかなりの割合が、あなたのウェブサイトに届かなくなります。ユーザーはChatGPT、Claude、またはPerplexityに質問し、その回答はそれらのモデルが参照できる情報をもとに合成されます。Mintlifyは、自社がホスティングするドキュメントサイト全体で30日間のトラフィック（約7億9,000万件のリクエスト）を測定し、AIコーディングエージェントが全リクエストの45.3%を占めたと報告しました。その内訳はClaude Codeが25.2%、Cursorが18.0%でした（ドキュメントにおけるエージェントトラフィックの現状、2026年4月3日公開）。その後の測定では、エージェントの割合は2026年7月のトラフィックの66%に達しました（2026年半期レポート、2026年7月29日公開）。これはウェブ全体ではなく、あるベンダーのフリートに関する数値ですが、ドキュメントへのエージェントトラフィックについて公開された測定結果としては最大規模です。私たち自身の数値はもっと小さいものの、同じ方向に推移しています。

AIクローラーがあなたのドキュメントを引用するには、あなたのドキュメントを読み取れる必要があります。つまり、クリーンなサーバーサイドレンダリングHTML、セマンティックな見出し、sitemap.xml、理想的には正規コンテンツを一覧表示するllms.txt、そしてrobots.txtにおける主要なAIユーザーエージェント向けのAllowが必要です。Notionでは、これらのほとんどが提供されません。HTMLはJavaScriptに大きく依存しており、llms.txtもなく、AIクローラーの回答率も実証的に低いのです。

回答エンジンに引用してもらいたいなら、あなたのドキュメントはクローラーから見て、ドキュメントサイトのように見える必要があります。データベースビューを中心に構築されたSPAのように見えてはいけません。

5. ドキュメントのパフォーマンス予算は厳しい#

ドキュメントページは瞬時に表示されるべきです。これは単なるスタイル上の好みではなく、コンバージョンを左右する要因です。ユーザーは午前2時にデバッグ作業をしていて、すでに苛立っています。読み込みにかかる1秒ごとに、諦めて代わりにチケットを起票する可能性が高まります。

Notionで公開したページをLighthouseで計測してみてください。数値はあまり良くありません。実際の携帯回線では、Largest Contentful Paintは通常3〜5秒の範囲に収まり、Reactツリーが段階的にハイドレーションされるためCumulative Layout Shiftも目立ちます。また、解析すべきJavaScriptが大量にあるため、Total Blocking Timeも高くなります。

社内Wikiなら誰も気にしません。しかし、ユーザーが開いているほかの無数のタブと競わなければならない顧客向けドキュメントでは、大きな意味を持ちます。静的にレンダリングされたMarkdownへ移行したところ、ドキュメントページの離脱率が大幅に下がりました。こうした数値は、一度目にしてしまうと、もう見なかったことにはできません。

6. ロックインは現実のものであり、積み重なっていく#

Notionにはエクスポート機能があります。私は使ったことがあります。出力されるのは、ファイル名が壊れたHTMLまたはMarkdownファイルのフォルダーで、notion.so URLを指す内部リンクが壊れていたり、埋め込みデータベースが読みにくい表に平坦化されていたり、期限切れになる署名付きS3 URLを指す画像参照が含まれていたりします。400ページをエクスポートしてから、そのエクスポート結果を修正するだけで1週間かかります。

ロックインとは、エクスポートボタンが存在するかどうかではありません。エクスポートされたデータが、移行作業なしに別のツールで役立つほど十分に構造化されているかどうかということです。その基準では、Notionのエクスポートは弱いと言えます。使い続けるほどページが蓄積し、移行コストは高くなっていきます。離れようとしたときに初めて気づくのです。

Gitリポジトリ内のMarkdownは、正反対の性質を持っています。「エクスポート」はgit cloneです。ディレクトリを別の静的サイトジェネレーターや別のドキュメントプラットフォームに移すことも、単に生ファイルとして公開することもできます。この可搬性は、ドキュメントシステムが持ち得る特性の中で、最も過小評価されているものです。必要になるその日まで価値を感じることはありませんが、そのときには何にも代えがたい価値を持ちます。

7. 権限、下書き、そしてウィキとドキュメントの分離#

根本的な問題は、ウィキとドキュメントが、エディター上では同じように見えても異なるプロダクトだということです。

ウィキは私たちのためのものです。下書き、未完成のページ、社内限定のセクション、2人のチームリードがコメント欄で意見を異にしているページ、決して公開すべきでないランブック、そして実際には忘れ去られるための場所にすぎない「アーカイブ」フォルダーがあります。対象者が細かく分かれているため、権限モデルもきめ細かくなります。

ドキュメントは彼らのためのものです。公開版は1つだけで、中途半端な状態はなく、読者に下書きが見えることも、公開URLからコメントスレッドが見えることもありません。下書きは本番ツリーではなく、プルリクエストの中に置かれます。対象者がインターネット全体だからこそ、権限モデルは二者択一、つまり公開されているかどうかになります。

Notionは最初の用途向けに作られ、2つ目の用途には継ぎはぎで対応しています。その結果、社内向けハンドブックのページと顧客向けAPIドキュメントが同じツリーに混在するワークスペースになり、設定を1つ間違えるだけで、誤ったページが公開されてしまいます。私はこれが3社で起きるのを見ましたし、自分でも危うく同じことをするところでした。

「ウィキ」と「ドキュメント」の境界は、物理的に分ける価値があります。システムも、リポジトリも、レビューのワークフローも、ドメインも別にするのです。

代わりに何を使うのか？#

コメント、意見、下書き、インラインデータベースが必要な社内向けのもの、つまり戦略文書、RFC、会議メモ、ハンドブックなどには、今でもNotionが適切なツールです。私たちはNotionの使用をやめたわけではありません。間違った用途で使うのをやめたのです。

顧客向けのドキュメントは、gitリポジトリに置き、markdownで記述し、プルリクエストでレビューして、静的サイトとして公開しています。構成は意図的に退屈なものにしています。ドキュメントはコードの隣にあるため、同じPRで更新されます。gitの履歴がバージョン履歴になります。リポジトリがエクスポートになります。CIでリンクチェックを実行します。公開サイトは、適切な見出し、サイトマップ、llms.txt、そして言語ごとに1つのURLを備え、サーバーサイドでレンダリングされます。

Docsbook、Docusaurus、Mintlify、VitePressのいずれを使うか、あるいはeleventyで独自に構築するかは、見た目ほど大きな決定ではありません。より大きな決定は、その前にあります。これらのドキュメントはチームのためのものですか、それとも世界に向けたものですか？世界に向けたものなら、Wikiから取り出し、プロダクトと同じように扱うシステムに移しましょう。

私たちがDocsbookを作ったのは、「markdownのgitリポジトリ」から「SEO、AIチャット、15言語、アナリティクスを備えた公開ドキュメントサイト」までを、CIステップ1つも、docusaurus.config.jsもなしに、5秒で実現したかったからです。これが、私たちが販売するプロダクトを持つに至ったこの物語のバージョンです。同時に、これは私たちが歩んだ正直な道でもあります。最初にNotionを試し、次にDocusaurusを試しました。そして、Notionのシンプルさと本格的なドキュメントサイトのエンジニアリング上の特性を両立させたかったのに、それを実現したものを他の誰も作っていなかったため、最終的にDocsbookを書くことになりました。

守る価値のある唯一の原則#

自社で働いていない人にもドキュメントを見つけてもらう必要があるなら、それはSEOおよびAIによる発見性のためのプロダクトです。そのように扱いましょう。ソース管理に置き、HTMLとしてレンダリングし、すべての言語に実際のURLを付け、JavaScriptを実行しなくてもクローラーが読めるようにしてください。

Wikiは、すでに内側にいる人たちのためのものです。ドキュメントは、まだ外側にいて中を覗いている人たちのためのものです。第一印象を与える機会は一度きりで、それはたいてい午前2時、読者が苛立ちながらスマートフォンで見ているときに訪れます。ドキュメントが書かれた会議のためではなく、その読者のために作りましょう。

それが教訓です。それ以外はすべて実装の詳細です。

無料で始める — クレジットカード不要

次のステップ#

Updated

このページは役に立ちましたか？

提供： Docsbook