ビックテックでは膨大なドキュメントをどう管理しているのですか?
- User
ビックテックでは膨大なドキュメントをどう管理しているのですか?
- Assistant
以下は、Google / Amazon / Microsoft / Meta などの“ビッグテック”で実際に行われている ※ことをベースに、膨大な開発ドキュメント(設計書・API 仕様・運用 Runbook・ADR など)を整備/発見/更新し続けるための代表的なアプローチです。
(※社外公開情報・OSS・元社員の発言・登壇資料から再構成しています)
1. 情報アーキテクチャ:まず「1ヶ所に集約」する
目的 代表的な実装例 単一エントリポイント (Single Entry Point) • Google: “go/link” 文化 + g3docポータル• Microsoft: “docs” サブドメイン + Azure DevOps Wiki• Meta: “Workplace” + “internal docs portal”組織横断検索 社内版 Google Search / Elasticsearch / Azure Cognitive Search などで すべてのリポジトリ・Wiki・チケットをフルクロール 検索窓ひとつ叩けば、コードも設計書も Slack 会話も一括ヒットする――が UX の出発点です。
2. “Docs-as-Code”:ドキュメントを コードと同じリポジトリ・ワークフロー に
- リポジトリ配置
myservice/ ├─ src/ └─ docs/ ├─ API.md ├─ design_overview.md └─ runbook.md - フォーマットは共通で軽量
- Markdown(.md) or reStructuredText(.rst)
- linter で書式チェック / リンク切れ検知
- Pull Request が唯一の変更経路
- コードレビューと同時にドキュメントもレビュー
- CI でビルド → ステージングサイト自動公開 → 承認後マージ
これにより
• バージョン管理(差分・責任者)が明確
• リリースと同時に docs も更新
となり “ドキュメントが腐る” 速度を大幅に抑えます。
3. 自動生成 & テンプレート化
対象 典型ツール / 手法 ポイント API リファレンス OpenAPI / gRPC → protoc-gen-doc,swagger-codegenCI で .proto → HTML を毎回生成 ライブラリ API Javadoc / TypeDoc / Sphinx / DocFX コードコメントから静的サイト SLO / メトリクス Terraform → terraform-docsIaC から自動的にテーブル化 Runbook / PagerDuty YAML で運用手順 → 内部サイトにレンダリング 「誰でも開ける PDF」を禁止し Web 化 └ “人が最後に書くのはストーリーだけ” というスタンスで、変更点を機械が先に埋めます。
4. ガバナンス:誰がどのドキュメントを守るのか
-
OWNERS ファイル(Google, Meta)
- リポジトリ or /docs 配下に コードオーナーと同一の reviewer を記載
- PR 作成と同時に自動でレビュー要求が飛ぶ
-
ドキュメント SLA / SLO
- 「運用 Runbook は PagerDuty rotation 更新から◯日以内にレビュー必須」
- GitHub Action / Azure Pipeline で期限切れアラート
-
ライフサイクルポリシー
- ADR の “Superseded” ステータス、アーカイブ用ラベル運用
- 定期ジョブで「最終更新が 1 年以上前」のファイルをリストアップ → チーム OKR に組み込む
5. 可観測性:DocOps のメトリクス
メトリクス 収集方法 (例) 使い方 coverage (%) リポジトリ数 / docs 付きリポジトリ数 四半期レビューで改善ターゲット決定 outdated count “最終更新 > 180日” なページ数 アラート・ダッシュボード broken links markdown-link-check失敗数PR ブロッカー pageviews / search failures 社内 Google Analytics 情報発見性のボトルネック分析 「ドキュメントも SLO を持つ」という DevOps の延長が DocOps 文化です。
6. インフォーマル情報の“発酵”も検索対象に
- Slack / Teams の公開チャンネルをログ集約 → 検索インデックスへ
- PR コメントやデザインレビューの記録を自動エクスポート → Docs Portal に紐付け
- 社内 TechTalk / RFC を録画+文字起こし → トランスクリプト全文検索
これにより「誰かが昔言ってた」を再発明せずに済みます。
7. まとめ:ビッグテック流ドキュメント運用5原則
- Single Entry Point:情報の入り口は1つだけ
- Docs-as-Code:コードと同じレポ・PR・CI
- Auto-Gen First:生成できるものは書かない
- Ownership & SLA:責任者と期限を明示
- Observable Docs:メトリクスで腐敗を検知
このフレームを小規模チームに落とす場合は、
• GitHub Wiki → Markdown in repo へ移行
• GitHub Actions でmkdocs + mermaid自動デプロイ
• CODEOWNERS と Renovate で更新自動検知
といった“ミニ DocOps”から始めると導入コストを抑えつつ効果を得られます。 - リポジトリ配置
Other models, same or similar prompt
Responses were produced in different, uncontrolled contexts (system prompts, settings, prior turns). This is not a benchmark.