ツールと管理方法・ドキュメントが腐る理由と定期レビュー

Docs as Code による管理

「Docs as Code」とは、ドキュメントをコードと同じリポジトリに置き、Markdownで記述してGitで管理するアプローチです。エンジニアチームにとって最も親和性が高い方法であり、多くのプロダクションチームで採用されています。

メリット	具体的な効果
コードと同じPRでレビューできる	「コードを変えたのにドキュメントが古いまま」をPRレビューで気づける
変更履歴が追跡できる	`git log` / `git blame` で「誰がいつ、なぜ変えたか」がわかる
CIで品質チェックできる	リンク切れ検出、Markdownlint、スペルチェックを自動化できる
ブランチを使った提案ができる	「仮説的な変更」をブランチで提案し、レビューを通じて議論できる

リポジトリ内のドキュメント構成例

docs/ ディレクトリを作り、docs/coding-standards.md、docs/api-guidelines.md、docs/adr/（ADRの連番ファイル群）、docs/CHANGELOG.md という構成が一般的です。README.md からこれらへのリンクを貼ることで、新メンバーがエントリーポイントを見つけやすくなります。

Notion / Confluence との使い分け

Git + Markdownがすべてのドキュメントに向いているわけではありません。ドキュメントの性質によってツールを使い分けることが重要です。

ツール	向いているドキュメント	向いていないドキュメント
Git + Markdown	技術仕様・コーディング規約・ADR・APIガイドライン。コードと密接に関連するもの	非エンジニアが頻繁に編集するもの。リアルタイムのコラボレーションが必要なもの
Notion / Confluence	意思決定ログ・チーム方針・ミーティングノート・ロードマップ。非エンジニアも触れるもの	コードと連動して変更されるべきもの。バージョン管理が重要なもの
Storybook	UIコンポーネントの仕様・バリエーション・Props一覧。「動くドキュメント」として管理	テキスト主体の説明。コンポーネント以外の設計方針
OpenAPI (Swagger)	REST APIの仕様書。コードのアノテーションから自動生成できる	APIの「なぜ」や設計の背景。それはAPIガイドラインに書く

自動生成ツールの活用

自動生成できる部分は積極的に自動化し、手で書くドキュメントは「コードから読み取れない情報（なぜ・背景・判断理由）」に集中しましょう。

ツール	生成されるドキュメント	特徴
OpenAPI / Swagger	APIエンドポイントの仕様書（エンドポイント一覧・パラメータ・レスポンス例）	コードのアノテーションから自動生成。変更がドキュメントに即反映される
Storybook	Reactなどのコンポーネントカタログ（Props・Story・インタラクション例）	「動くドキュメント」。デザイナーとエンジニアの共通言語になる
TypeDoc / JSDoc	ソースコードのコメントからAPIリファレンスを生成	関数のパラメータ・戻り値・使用例を自動で HTMLドキュメント化
dbdocs / SchemaSpy	データベーススキーマからER図・テーブル定義書を自動生成	マイグレーションと連動させると常に最新のDB構造が可視化される

なぜドキュメントは腐るのか

ドキュメントは「書いたら終わり」ではありません。むしろ書いた後の維持こそが難しく、多くのチームがここで失敗しています。まず「ドキュメントが腐るプロセス」を具体的に見てみましょう。

Text — ドキュメントが腐る12ヶ月シナリオ

Month 1: コーディング規約を整備。チームに周知。「良いものができた」

Month 3: 新しいライブラリ導入に伴い、一部のルールが実態と合わなくなる。
         「後で直そう」と誰かが思うが、誰も直さない。

Month 6: ドキュメントの3割が実態と乖離している状態に。
         新メンバーがドキュメント通りに実装すると、レビューで指摘される。

Month 9: 「あのドキュメントは古いから参考程度にして」という言葉が
         飛び交うように。信頼性が失われ始める。

Month 12: 誰も見なくなる。「存在しないドキュメント」と同じ状態に。

腐る3つの根本原因

原因1: 実装が変わってもドキュメントが追いつかない
コードは毎日変わりますが、ドキュメントの更新は後回しにされがちです。特に「コードを変えたならドキュメントも変える」という文化・ルールが明確でない場合、乖離が急速に広がります。「ドキュメントの更新」はタスクボードに上がらないため、見えない負債として蓄積されます。

原因2: 誰も更新しない「責任の空白」
「誰かが更新するだろう」という状態が続くと、誰も更新しません。これはコモンズの悲劇と同じ構造です。ドキュメントにオーナー（責任者）が設定されていないと、更新の責任が宙に浮きます。

原因3: 見つけられないドキュメントは存在しないのと同じ
どんなに良いドキュメントでも、メンバーが存在を知らなければ参照されません。あるチームでは、コーディング規約をGitリポジトリの docs/ に置いたが、新メンバーに案内しないまま3ヶ月が経過し、誰も知らない状態になっていた事例があります。

定期レビューの仕組み

「気が向いたら更新する」ではなく、四半期ごとの定期レビューをチームカレンダーに固定します。レビューは1時間程度のミーティング形式で行い、現在の実装との乖離を確認します。

Text — 四半期ドキュメントレビューミーティングアジェンダ（60分）

ドキュメントレビュー ミーティングアジェンダ（60分）

1. 前回レビューからの変更確認（10分）
   - CHANGELOGを読み合わせ
   - 前回決めたアクションの進捗確認

2. 実態との乖離チェック（30分）
   - 各セクションをオーナーが音読し、現状と違う箇所をその場で修正
   - 「これ今どうやってる？」を積極的に確認する
   - 修正が複雑な場合はIssueを作成し次のスプリントへ

3. 追加項目の検討（15分）
   - 直近3ヶ月のPRレビューコメントから繰り返し指摘されたものをリストアップ
   - 規約化すべきものを決定し、担当者を決める

4. 次回レビュー日時の確認（5分）
   - カレンダーへの登録確認
   - オーナーの引き継ぎがある場合は確認

オーナー制度とメタデータ管理

各ドキュメントに「オーナー（維持管理責任者）」を明記します。「オーナーだけが更新する」ではなく、「誰でも更新できるが、オーナーが最終的な責任を持つ」という位置付けにします。

Markdown — ドキュメントのフロントマター（メタデータ）

---
owner: "@yamada-taro"
reviewers: ["@sato-hanako", "@tanaka-ichiro"]
last_reviewed: "2025-09-01"
next_review: "2025-12-01"
status: "active"  # active / deprecated / draft
---

# コーディング規約 TypeScript 2025年版

（本文）

このメタデータをGitHub Actionsで定期的に読み込み、next_review を過ぎたドキュメントをオーナーにSlack通知するCIを作ることができます。「レビュー期限を人が管理する」から「システムが自動で知らせる」への転換が、ドキュメントの陳腐化防止に効きます。

変更時の通知・差分管理（GitHub Actions）

ドキュメントの変更もコードと同様にPRを通じてレビューします。さらに、docs/ への変更をトリガーにSlackに自動通知する仕組みを作ると、メンバーが最新の変更を見逃しません。

YAML — .github/workflows/notify-docs-change.yml

name: ドキュメント変更通知

on:
  push:
    branches:
      - main
    paths:
      - 'docs/**'

jobs:
  notify:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 2

      - name: 変更されたドキュメントを取得
        id: changed
        run: |
          FILES=$(git diff --name-only HEAD~1 HEAD -- docs/ | head -5 | tr '\n' ', ')
          echo "files=$FILES" >> $GITHUB_OUTPUT

      - name: Slackに通知
        uses: slackapi/slack-github-action@v1
        with:
          payload: |
            {
              "text": "📄 設計標準ドキュメントが更新されました",
              "blocks": [
                {
                  "type": "section",
                  "text": {
                    "type": "mrkdwn",
                    "text": "*変更ファイル*: ${{ steps.changed.outputs.files }}\n*コミット*: ${{ github.event.head_commit.url }}"
                  }
                }
              ]
            }
        env:
          SLACK_WEBHOOK_URL: ${{ secrets.DOCS_SLACK_WEBHOOK }}

CHANGELOGの設け方

ドキュメント全体の変更履歴を CHANGELOG.md として管理することで、「最近何が変わったか」を一箇所で確認できます。定期レビューの際に「前回から何が変わったか」を振り返るのに便利です。

Markdown — CHANGELOG.md の記載例

# CHANGELOG

## 2025-09-15
### 追加
- コーディング規約: TypeScriptのsatisfiesオペレーターに関するルールを追加 (#PR-234)
- アンチパターン集: Props Drillingのアンチパターンを追加 (#PR-231)

### 変更
- API設計ガイドライン: ページネーションのレスポンス形式を
  offset-basedからcursor-basedに変更 (#PR-228)

### 削除
- コーディング規約: Flow型の記述ルールを削除（TypeScript移行完了につき）(#PR-225)

## 2025-06-01
### 追加
- データモデル設計標準: 論理削除の運用ガイドラインを追加 (#PR-189)

次のPARTで扱うこと

PART 06（最終回）では、「実装との乖離を防ぐ工夫」（PRテンプレート・Linterとの連動・オンボーディングへの組み込み）と「使われるドキュメントにするための届け方」（タイトル設計・エントリーポイントの整備・参照文化の醸成）を解説し、シリーズ全体のまとめを行います。