Skip to content
TheChatArchiveThe Chat Archive
o3-2025-04-16· OpenAIHugging Face LMArena Human Preference 140K

ビックテックでは膨大なドキュメントをどう管理しているのですか?

From a Chatbot Arena battleThe same person sent this prompt to two anonymous models at once. Compare it with DeepSeekdeepseek-v3-0324’s answer.
  1. User

    ビックテックでは膨大なドキュメントをどう管理しているのですか?

  2. 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”:ドキュメントを コードと同じリポジトリ・ワークフロー に

    1. リポジトリ配置
      myservice/
      ├─ src/
      └─ docs/
          ├─ API.md
          ├─ design_overview.md
          └─ runbook.md
      
    2. フォーマットは共通で軽量
      • Markdown(.md) or reStructuredText(.rst)
      • linter で書式チェック / リンク切れ検知
    3. Pull Request が唯一の変更経路
      • コードレビューと同時にドキュメントもレビュー
      • CI でビルド → ステージングサイト自動公開 → 承認後マージ

    これにより
    • バージョン管理(差分・責任者)が明確
    • リリースと同時に docs も更新
    となり “ドキュメントが腐る” 速度を大幅に抑えます。


    3. 自動生成 & テンプレート化

    対象典型ツール / 手法ポイント
    API リファレンスOpenAPI / gRPC → protoc-gen-doc, swagger-codegenCI で .proto → HTML を毎回生成
    ライブラリ APIJavadoc / TypeDoc / Sphinx / DocFXコードコメントから静的サイト
    SLO / メトリクスTerraform → terraform-docsIaC から自動的にテーブル化
    Runbook / PagerDutyYAML で運用手順 → 内部サイトにレンダリング「誰でも開ける PDF」を禁止し Web 化

    └ “人が最後に書くのはストーリーだけ” というスタンスで、変更点を機械が先に埋めます。


    4. ガバナンス:誰がどのドキュメントを守るのか

    1. OWNERS ファイル(Google, Meta)

      • リポジトリ or /docs 配下に コードオーナーと同一の reviewer を記載
      • PR 作成と同時に自動でレビュー要求が飛ぶ
    2. ドキュメント SLA / SLO

      • 「運用 Runbook は PagerDuty rotation 更新から◯日以内にレビュー必須」
      • GitHub Action / Azure Pipeline で期限切れアラート
    3. ライフサイクルポリシー

      • ADR の “Superseded” ステータス、アーカイブ用ラベル運用
      • 定期ジョブで「最終更新が 1 年以上前」のファイルをリストアップ → チーム OKR に組み込む

    5. 可観測性:DocOps のメトリクス

    メトリクス収集方法 (例)使い方
    coverage (%)リポジトリ数 / docs 付きリポジトリ数四半期レビューで改善ターゲット決定
    outdated count“最終更新 > 180日” なページ数アラート・ダッシュボード
    broken linksmarkdown-link-check 失敗数PR ブロッカー
    pageviews / search failures社内 Google Analytics情報発見性のボトルネック分析

    「ドキュメントも SLO を持つ」という DevOps の延長が DocOps 文化です。


    6. インフォーマル情報の“発酵”も検索対象に

    • Slack / Teams の公開チャンネルをログ集約 → 検索インデックスへ
    • PR コメントやデザインレビューの記録を自動エクスポート → Docs Portal に紐付け
    • 社内 TechTalk / RFC を録画+文字起こし → トランスクリプト全文検索

    これにより「誰かが昔言ってた」を再発明せずに済みます。


    7. まとめ:ビッグテック流ドキュメント運用5原則

    1. Single Entry Point:情報の入り口は1つだけ
    2. Docs-as-Code:コードと同じレポ・PR・CI
    3. Auto-Gen First:生成できるものは書かない
    4. Ownership & SLA:責任者と期限を明示
    5. Observable Docs:メトリクスで腐敗を検知

    このフレームを小規模チームに落とす場合は、
    • GitHub Wiki → Markdown in repo へ移行
    • GitHub Actions で mkdocs + mermaid 自動デプロイ
    • CODEOWNERS と Renovate で更新自動検知
    といった“ミニ DocOps”から始めると導入コストを抑えつつ効果を得られます。

Responses were produced in different, uncontrolled contexts (system prompts, settings, prior turns). This is not a benchmark.