5万
ClickHouse では、開発者向けドキュメントをひとつのプロダクトと捉えており、ユーザーやオープンソースコミュニティのために常にその改善方法を模索しています。
今回、clickhouse.com/docs を Mintlify 上でリニューアルしたことをお知らせします。Mintlify は毎月数千万人の開発者に利用されているインテリジェントなナレッジプラットフォームで、Anthropic、Microsoft、Coinbase、Perplexity、そして今回 ClickHouse のヘルプセンター、サポートセンター、開発者向けドキュメントサイトを支えています。
なぜプラットフォームを移行したのか？
開発者向けドキュメントを取り巻く環境は、この 1 年だけでも劇的な変化を遂げました。現在では、開発者向けドキュメントへのトラフィックの半分以上が、人間だけではなくコーディングエージェントからもたらされています。この変化は、ドキュメントサイトに求められる要件も変化したことを意味します。これまで長年活用してきたプラットフォームである Docusaurus は素晴らしいものでしたが、「エージェント」が私たちのターミナルを席巻するはるか前に作られ、人間の読者のみを想定して設計されていました。
新しいドキュメントサイトに Mintlify を選んだのは、人間とエージェントの双方向を考慮してゼロから設計されたプラットフォームだからです。新プラットフォームへの移行によって、より高品質な開発者向けドキュメント体験の提供、迅速な改善サイクルの実現、そして私たちが真に注力したいこと、つまり利用者にとって最高のドキュメント体験を届けることに集中できるようになります。
何が変わったのか？
検索体験とエージェントアクセシビリティの向上
新しいドキュメントにアクセスすると、新しいランディングページと洗練された新 UI が出迎えます。検索と Ask AI を画面中央の目立つ位置に配置したのは、アクセスパターンの変化に対応し、探している答えをより早く見つけられるようにするための意図的な設計です。ドキュメント、ブログ、さらには GitHub Issues を横断して検索したり、Ask AI を使って質問に対する的確な回答を得たりできるようになりました。
エージェントをドキュメントに直接接続して最新の回答を得たいユーザーのために、ランディングページにはドキュメント用の MCP サーバーをセットアップするための手順とワンクリックコマンドを用意しました。この MCP サーバーには、サイト全体の検索ツール、シェル風のコマンドを使って仮想ファイルシステムを読み取り移動するツール、そしてエージェントが不正確・古い・わかりにくい・不完全なページを見つけた際に私たちのチームへフィードバックを送るツールが組み込まれています。
Claude Code でドキュメント用 MCP サーバーをセットアップするには、ターミナルから次のコマンドを実行するだけです。
claude mcp add --transport http clickhouse-docs https://clickhouse.com/mcp --scope userサイトはエージェントからのリクエストを自動で検知し、HTML ではなく Markdown を返すようになったため、より高速かつ少ないトークン数でコンテンツを処理できます。
よりシンプルな情報設計
以前よく寄せられたユーザーからのフィードバックに、トップナビゲーションに様々な製品領域や目的に応じた多階層のドロップダウンがあり、目的のページを探しにくいという声がありました。新しいサイトではナビゲーションを簡素化し、オープンソースの ClickHouse と ClickHouse Cloud の双方に共通するコアデータベース機能のドキュメントを、Cloud 固有の製品ドキュメントから切り離しました。
コアデータベースのドキュメントは、達成したい目的に基づいて次のセクションに整理されています。
- Get started: このセクションには、新しいクイックスタートエクスプローラー、移行ガイド、インストール手順、試用できるサンプルデータセットが用意されています。
- Concepts: ClickHouse を最大限に活用できるように、基本概念、コア製品機能の概要、ベストプラクティスをまとめています。
- Guides: 特定の目標を達成したり、ClickHouse を個別のユースケースに適用したりするための詳細なコンテンツを掲載しています。
- Reference: 関数、設定、データ型、フォーマット、テーブルエンジンなどのリファレンスドキュメントをまとめています。
Cloud、ClickStack、ClickHouse Managed Postgres といった特定の ClickHouse ソリューションのドキュメントは「Solutions」タブの下にまとめられ、同様の整理パターンに従っています。また、連携に関するドキュメントは、ClickPipes、言語クライアント、コネクタの 3 つの個別セクションに分割しました。
製品の各領域にわたって明確なユーザーの目的を意識してドキュメントを構成することで、より一貫したドキュメント体験を提供できるようになります。
API playground
API ドキュメントの利用者であれば、以前は別のプラットフォームへリダイレクトされていたことを覚えているかもしれません。現在はその必要がなくなり、Cloud と ClickStack の両方で、OpenAPI 仕様から生成されたドキュメントへサイト内から直接アクセスできます。API エクスプローラーの「Try it」ボタンをクリックして認証情報を入力すると、ClickHouse サービスからのレスポンスが安全に表示され、ブラウザから離れることなくすばやく API を試すことができます。
双方にとっての使いやすさの向上
Mintlify プラットフォームの導入は、利用者にとっても私たちにとっても、いくつかの使いやすさの向上をもたらします。各ページには、ページを Markdown としてコピーするオプション、Markdown を直接表示するオプション、MCP サーバーをセットアップするためのクイックリンクが用意されています。また、オフラインで読みたい方向けに、ページを .pdf としてダウンロードするオプションも追加しました。
ドキュメントには以前からフィードバック用ウィジェットを設置していましたが、新しいプラットフォームによって、いただいたフィードバックの追跡や対応のしやすさが大幅に向上しました。各フィードバックのトリアージ、社内コメントの追加、対応状況のステータス管理ができるようになっています。
世界中に分散したリモートファースト企業である私たちは日常的に Slack を多用しており、Slack エージェント経由でのドキュメント更新機能や Notion スタイルのビジュアルエディタの導入により、利用者へのドキュメント更新をさらに迅速に行えるようになります。また、ドキュメントの自動コンテンツ保守を行うために、Mintlify の automations 機能の活用も楽しみにしています。
単一リポジトリからのコミュニティへの提供
コミュニティのアクティブメンバーであればご存知の通り、私たちのドキュメントは従来、ClickHouse/ClickHouse(リファレンスドキュメント用)と ClickHouse/clickhouse-docs(ガイド、チュートリアル、製品ドキュメント用)の 2 つのリポジトリに分かれていました。今回、すべてのドキュメントをコア開発リポジトリへと統合しました。
エージェントが信頼できる情報源としてドキュメントに依存するようになった今、コードの変更に合わせてドキュメントを最新の状態に保つことがこれまで以上に重要になっています。
今回の統合により、ドキュメントをコード、そしてそのコードを書くエンジニアやコミュニティのコントリビューターのすぐそばに置くことができ、AI による自動レビューでドキュメントの乖離を検知しやすくなります。また、ドキュメントに関する問題を報告する際に追加のコンテキスト切り替えを必要とせず、単一の場所からコミュニティを支援できるようになります。さらに、ドキュメントへの貢献も、コードへの貢献と同様に system.contributors に名前が載るようになります。
ドキュメントは非常に価値がありながらも見過ごされがちなオープンソースソフトウェアの側面ですが、ClickHouse への最初のコントリビューションを行うには最適な場所です。小さくとも同様に価値のあるドキュメント PR を通じて、より多くの初参加コントリビューターがオープンソースの世界へ踏み出すことを楽しみにしています。
多言語サポートの拡充
現在、ドキュメントは英語、日本語、韓国語、簡体字中国語、ロシア語で提供されています。新サイトの立ち上げに伴い、ブラジルポルトガル語、スペイン語、フランス語、アラビア語へと対応言語を拡大しました。これらの言語における LLM 翻訳の品質維持には最善を尽くしていますが、精度をさらに向上させるために、コミュニティ内の各ネイティブスピーカーからのコントリビューションを歓迎しています。
組み込みドキュメント(Embedded documentation)
Alexey Milovidov による貢献
ClickHouse 26.6 リリースでは、ターミナル作業を好む方向けに使いやすさの大幅な改善が行われました。クライアントから直接リファレンスドキュメントを検索し、閲覧できるようになっています。help <topic> または \h <topic> と入力するだけで、すぐにドキュメントを表示できます。このドキュメントは ClickHouse Reference や、稼働中のサーバーの /docs からも利用可能です。
これは、新しいシステムテーブル system.documentation の導入により実現しました。これまでも system.functions や system.settings のようないくつかのテーブルにはドキュメントが組み込まれていましたが、未記載の領域も存在していました。今回、テーブルエンジン、データベースエンジン、フォーマット、集約関数コンビネータ、辞書レイアウト、辞書ソース、データスキッピングインデックス型、ディスク型に関する新しいシステムテーブルが追加され、それぞれに対応するドキュメントが収録されるようになりました。
この機能のデモは、26.6 リリース発表会(英語)で Alexey が紹介していますのでぜひご覧ください。
ご意見をお聞かせください
新サイトについてのご意見やフィードバックをぜひお寄せください。各ドキュメントページ下部のフィードバックフォーム(高評価・低評価ボタン)、「raise an issue」ボタン、またはコミュニティ Slack からドキュメントチームに直接ご連絡いただけます。いただいたフィードバックは、より良いドキュメント体験を築くための大きな力となります。
