データ基盤のドキュメントは、「書くこと」ではなく「自動生成と手動更新の境界線を正しく引くこと」が成否を分けます。コードから生成できるものはすべてdbt docsやメタデータカタログに任せ、人間が書くべきは「なぜこの設計にしたか」「障害時にどうするか」「新人は何から読めばよいか」の3種類だけに絞る。これが陳腐化を防ぐ唯一の現実解です。全部を人力で書こうとした瞬間、ドキュメントは書かれた翌日から腐り始めます。
本記事では、データ基盤ドキュメントを4層に分類し、自動生成の仕掛け・運用テンプレート・鮮度維持戦略・ツール選定までを解説します。D-09(データカタログ運用)と連動させることで、ドキュメント資産の価値が数倍に高まります。
データ基盤ドキュメントが陳腐化する理由
データ基盤のドキュメントが陳腐化する理由は三つあります。(1)書くべき範囲が広すぎて誰も全貌を把握できない、(2)更新責任者が曖昧で「気づいた人が直す」という無責任体制になっている、(3)ドキュメントとコードの更新タイミングが分離している、の三点です。特に三点目は致命的で、コード変更時にドキュメント更新を忘れると、翌週には現実との乖離が始まります。
解決策は「コードから自動生成する領域を最大化し、人間が書く部分を最小化する」というアプローチです。A-09(メタデータ管理)で解説するように、メタデータ駆動のドキュメンテーションが現代の主流です。
ドキュメントの4層分類
データ基盤ドキュメントは、対象読者と更新頻度によって4層に分けると整理できます。下層ほど自動化しやすく、上層ほど人間の判断と経験が必要になります。各層で「誰が書くか」「誰が読むか」「どのツールで管理するか」を明確にすることが、陳腐化を防ぐ第一歩です。
| 層 | 種類 | 目的 | 更新頻度 | 管理者 |
|---|---|---|---|---|
| Layer 1 | テーブル定義・リネージ | 構造把握・データ発見 | コード変更時(自動) | データエンジニア |
| Layer 2 | ビジネス用語集・指標定義 | 共通言語の確立 | 月次(手動) | データスチュワード |
| Layer 3 | 運用Runbook・SOP | 障害対応・定型作業 | 障害・変更発生時 | オンコールリーダー |
| Layer 4 | アーキテクチャ決定記録(ADR) | 設計意図の継承 | 重要な意思決定時 | テックリード |
【ドキュメント4層ピラミッド】
/\
/ \
/ L4 \ ADR・設計意図
/------\
/ L3 \ Runbook・SOP
/----------\
/ L2 \ 用語集・指標定義
/--------------\
/ L1 \ テーブル定義・リネージ
/------------------\
※ 下層ほど量が多く自動化しやすい。上層ほど判断・経験が必要で量は少ない。コードからの自動生成
Layer 1のドキュメントは、dbt docsやカタログ連携でほぼ完全に自動生成できます。B-01(dbt入門)で作成したmodelのdescriptionやschema.ymlが、そのまま公開ドキュメントになります。ポイントは「コード変更時にドキュメント生成ジョブを必ず実行する」仕組みを組み込むことです。GitHub ActionsやCI/CDパイプラインに組み込めば、開発者が意識しなくても最新のドキュメントが維持されます。
# GitHub Actions設定例(dbt docs自動生成)
name: dbt-docs
on:
push:
branches: [main]
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- run: dbt deps && dbt docs generate
- uses: actions/upload-artifact@v4
with:
path: target/この設定で、mainブランチへのmergeのたびにdbt docsが自動生成され、静的サイトとして公開される状態が実現します。開発者の作業は「modelにdescriptionを書く」という一手間だけで、ドキュメントの最新性は自動的に保たれます。
運用ドキュメントの書き方テンプレート
Layer 3の運用ドキュメント(Runbook、SOP)は手動で書く必要がありますが、テンプレートを用意することで品質と再利用性を確保できます。テンプレートがあれば、新人でも既存のRunbookと同じ構造で書けるため、ばらつきが減り、読む側の負担も軽くなります。D-11(インシデント管理)のポストモーテムテンプレートと整合性を持たせると、運用知識が体系化されます。
| 項目 | 内容 | 必須 |
|---|---|---|
| タイトル | 対象の作業名または障害パターン名 | 必須 |
| 対象読者 | オンコール担当・特定ロールなど | 必須 |
| 前提条件 | 実行前に必要な権限・ツール | 必須 |
| 手順 | 番号付き箇条書き、コピペ可能なコマンド | 必須 |
| 確認方法 | 成功を確認するクエリやチェック項目 | 必須 |
| ロールバック | 失敗時の戻し方 | 推奨 |
| 関連リンク | ADR、カタログ、Slackチャンネル | 推奨 |
| オーナー | 責任者名・最終更新日 | 必須 |
ドキュメント鮮度の維持戦略
手動で書かれたドキュメントを陳腐化させないためには、(1)オーナーと最終更新日の明示、(2)PRレビュー時のドキュメント更新チェック、(3)四半期棚卸し、の三点セットが効果的です。特にPRレビュー時のチェックは強力で、「このコード変更に対してドキュメント更新は?」という項目をPull Requestテンプレートに組み込むだけで、更新漏れが激減します。D-03(データ品質管理)やD-09(データカタログ運用)でも同様の仕組みが推奨されています。
四半期棚卸しでは、オーナーが不在になったドキュメント(退職・異動)と、最終更新日が6か月以上前のドキュメントを抽出し、再評価します。「もう不要」「継続」「更新必要」の3択で判断し、不要なものは思い切ってアーカイブします。アーカイブに勇気が要る気持ちはわかりますが、古い情報が混ざっているドキュメント群は、新規閲覧者の信頼を損ねます。
ツール選定
ドキュメント管理ツールは、「コードに近いもの」と「文章中心のもの」を明確に分けて選定します。コードに近いLayer 1とLayer 3の一部は、Gitリポジトリ(Markdown+静的サイトジェネレータ)で管理するのが王道です。変更履歴・レビュー・自動デプロイがそのまま使えます。一方、Layer 2のビジネス用語集やLayer 4のADRは、Notion・Confluence・GitBookといった文章管理ツールの方が、非エンジニアも含めた編集と検索が容易です。
ツールは増やしすぎないことが肝心で、3〜4個に絞るのが現実的です。「データカタログ(Layer 1)」「GitHub(コード関連)」「社内Wiki(業務文脈)」「ADR専用リポジトリ」の組み合わせが、多くの組織で機能するパターンです。D-02(ガバナンス体制)で定めるオーナーシップと整合させて、各ツールに責任者を設けます。
まとめ
データ基盤のドキュメンテーション戦略は、「自動生成と手動更新の境界線」の設計がすべてです。4層分類で対象を整理し、Layer 1はdbt docs等で自動化、Layer 3は標準テンプレート、Layer 4はADRで意思決定を記録。この構造を維持すれば、README一つで始まったドキュメントが、組織の知的資産へと育っていきます。
よくある質問
Q. データ基盤のドキュメントで最低限必要なものは?
テーブル定義書(カラム説明・型・制約)、パイプライン構成図、障害対応Runbook、データ辞書の4つです。この4つがあれば新人のオンボーディングと障害対応の最低限は回ります。余裕があればADR(アーキテクチャ決定記録)を追加すると、設計意図の継承が可能になります。
Q. ドキュメントの陳腐化をどう防ぎますか?
dbt docsやデータカタログによる自動生成を基本とし、手動ドキュメントにはオーナーと更新期限を設定します。PRレビュー時のドキュメント更新チェックも有効で、Pull Requestテンプレートに「関連ドキュメントの更新有無」を組み込むと更新漏れが激減します。四半期棚卸しも忘れずに実施しましょう。
Q. Notionとコードリポジトリ、どちらで管理すべきですか?
コードに近いもの(テーブル定義・パイプライン設定・dbt docs)はリポジトリ、運用手順・意思決定ログ・ビジネス用語集はNotionなどのWikiが適しています。両方を使い分ける場合、各ツールに明確な責任範囲を設定し、どちらを見れば何があるかが一目でわかる状態を維持することが重要です。