VitePressで作る内部開発者向けドキュメントサイト
#SRG（Service Reliability Group）は、主に弊社メディアサービスのインフラ周りを横断的にサポートしており、既存サービスの改善や新規立ち上げ、OSS貢献などを行っているグループです。
本記事は、CyberAgent Group SRE Advent Calendar 2025の15日目の記事になります。分散した社内情報をesa.ioとVitePressで一元化するサイトの構築事例に加え、ドキュメントの品質を高めるためにDiátaxisでの運用を検討しており、それらについて紹介するものです。
はじめに
現在、私たちは内部開発者向けのドキュメントサイトを構築しています。このプロジェクトの目的は、開発に必要なドキュメントを一元化し、開発者が必要な情報に素早くアクセスできる環境を提供することです。本記事では、サイト構築に至った背景、採用したアーキテクチャ、技術選定の理由、そしてドキュメントの品質を高めるための取り組みについて紹介します。なお、本サイトは現在構築・検討段階であり、本格的な運用はこれからとなります。
抱えていた課題
このサイトを構築することにした背景には、大きく2つの課題がありました。
1つ目は、ドキュメントが様々な場所に分散していたことです。歴史的な経緯により、社内の情報はesa.ioとNotionの両方に散らばっていました。そのため、開発者は「探している情報がどこにあるのかわからない」という状態に陥っていました。
2つ目は、ユースケース視点のドキュメントが不足していたことです。ドキュメント自体は存在していましたが、その多くはツールや機能ごとに整理されていました。開発者が「○○をしたい」と考えたとき、そのタスクを完了するためには複数のドキュメントを横断して読む必要があるケースがありました。適切な情報にアクセスするには、あらかじめシステムやドキュメントの全体像を把握している必要があり、特に新しくチームに加わったメンバーにとってはキャッチアップが難しい場合がありました。
これら２つの課題を解決するために、ユーザが必要な情報にすぐアクセスするための場所と構成を構築する必要があり、ドキュメントサイトの提供とDiátaxisの導入を検討しています。
システムアーキテクチャ
今回構築したサイトは、esa.ioに蓄積されているナレッジを集約し、閲覧しやすい形で提供するものです。アーキテクチャの全体像は以下の通りです。
esa.ioからのデータ同期
サイトに掲載するコンテンツのマスターデータはesa.ioにあります。GitHub Actionsを使用し、1日1回の定期実行でesa.ioのAPIを呼び出しています。特定のディレクトリ配下や特定のタグが付与されたドキュメントを対象に、本文だけでなく画像も含めて取得し、VitePressで扱えるMarkdown形式に変換してリポジトリに保存します。これにより、esa.io上でドキュメントが更新されれば、翌日には自動的にサイトへ反映される仕組みとなっています。
Cloudflare PagesとZero Trustによるホスティングとセキュリティ
生成された静的サイトはCloudflare Pagesでホスティングしています。Cloudflare Pagesを採用した理由は、GitHubリポジトリと連携して手軽に構築できる点や、Pull RequestごとにプレビューURLが発行されるため確認が容易である点です。
また、社内向けサイトであるため外部からのアクセス制限が必須となりますが、これにはCloudflare Zero Trustを活用しています。すでに社内で導入されていたCloudflare Zero Trustの環境を利用することで、認証されたユーザーのみがサイトにアクセスできるセキュアな環境を容易に実現できました。
検索機能
情報の探しやすさを向上させるため、VitePress標準の全文検索機能を活用しています。これにより、サイト内のドキュメントを横断的に検索することが可能です。現時点では標準機能で十分ですが、将来的に検索要件が高度化した場合には、Algoliaなどの外部検索サービスの導入も検討できる構成にしています。
技術選定
内部開発者ポータル（IDP）やドキュメントサイトの構築において、Spotifyが開発したBackstageは非常に有名な選択肢です。しかし、今回はあえてBackstageを採用せず、VitePressを選定しました。
その最大の理由は、今回の目的に対してBackstageはオーバースペックであると判断したためです。Backstageはサービスカタログ、ソフトウェアテンプレート、豊富なプラグイン機構など、開発ライフサイクル全体を管理するための強力な機能を備えています。一方で、今回のプロジェクトの主目的はあくまで「ドキュメントを一元化し、閲覧しやすくすること」にありました。
VitePressはVue.jsベースの静的サイトジェネレーターであり、非常に軽量で高速です。Markdownベースでシンプルにドキュメントを管理・記述できるため、ドキュメントサイトとしての用途に特化しています。構築やメンテナンスのコストを抑えつつ、高速な閲覧体験を提供できる点が、今回の要件に最適でした。
コンテンツ設計
ドキュメントを集約するだけでは、「何を書けばいいかわからない」「読みづらい」という根本的な問題は解決しません。そこで、ドキュメントの構成指針として「Diátaxis（ダイアタクシス）」フレームワークの採用を検討しています。
Diátaxisは、ドキュメントをユーザーのニーズに基づいて以下の4つのタイプに分類するアプローチです。
- Tutorials（チュートリアル）: 学習指向。手を動かしながら学ぶレッスン。
- How-to Guides（ハウツーガイド）: 問題解決指向。特定のタスクを完了するための手順。
- Reference（リファレンス）: 情報指向。技術的な詳細仕様やパラメータの説明。
- Explanation（説明）: 理解指向。背景、概念、設計思想などの解説。
従来はツール単位で情報が整理されていたため、ユースケース（How-to）と仕様（Reference）が混在しがちでした。Diátaxisに準拠することで、執筆者は「何をどこに書けばいいか」が明確になり、読者は自分の目的に合った情報をすぐに見つけられるようになります。社外のいくつかのテックブログでも導入事例が報告されており、ドキュメントの品質向上に効果的であると考えられています。
おわりに
現在はサイト自体の構築が完了し、コンテンツを精査している段階です。Diátaxisフレームワークの運用ルール策定などの運用面はこれからとなります。ドキュメントは「書いて終わり」ではなく、継続的にメンテナンスされ、活用されることが重要です。今後も開発者が快適に情報を得られる環境を目指し構築を続けていきます。
SRG では一緒に働く仲間を募集しています。
ご興味ありましたらぜひこちらからご連絡ください。