ドキュメントは「書く」より「最新を保つ」が難しい。自動化が鍵。

結論

データカタログが使われない理由は、「コードと分離している」から。

よくある失敗パターン

Phase 1：導入（盛り上がる）

「データカタログ導入しました！」
「これでデータの所在が分かる！」
「便利！」

Phase 2：3ヶ月後（放置）

「あれ、このテーブル載ってない...」
「情報が古い...」
「結局、詳しい人に聞くか...」

Phase 3：1年後（廃墟）

「データカタログ？ああ、あったね...」

なぜ使われなくなるのか

原因1：手動更新が必要

テーブルが増えるたびに、手動でカタログを更新する必要がある。

面倒だから、誰もやらない。

原因2：コードと分離している

SQLファイルとカタログが別の場所にある。

修正するときに、両方更新する必要がある。

原因3：「ドキュメントは後回し」文化

「まず動くものを作る。ドキュメントは後で」

→ 後でやることは、永遠にやらない。

解決策：dbt docs

dbtを使えば、コードと一緒にドキュメントを管理できます。

仕組み

# schema.yml（SQLと同じディレクトリに置く）
models:
  - name: fact_sales
    description: 売上の事実テーブル
    columns:
      - name: order_id
        description: 注文ID
      - name: amount
        description: 金額（税込、円）

自動生成

dbt docs generate
dbt docs serve

これだけで、最新のドキュメントサイトが生成される。

メリット

項目従来のカタログdbt docs
更新手動コードと同時
最新性古くなりがち常に最新
管理場所別システムコードと同じ
習慣化難しいPRに含まれる

導入のコツ

コツ1：PRでドキュメントもチェック

「ドキュメントが書かれていないPRはマージしない」をルール化。

コツ2：最初から完璧を目指さない

最低限の description から始める。

description: 売上データ

これだけでも、ないよりマシ。

コツ3：見る習慣を作る

「分からないことがあったら、まずdbt docsを見る」を習慣化。

まとめ

ドキュメントは「書く」より「最新を保つ」が難しい。

dbt docsで、コードと一緒に管理すれば、自動で最新が保てます。