
Docs as Code 実践 — ドキュメントをコードと一緒に管理する
前の記事
はじめに
「Confluence に書いたドキュメントが古いまま放置されている」
「README は更新されているのに、Confluence の手順書は半年前のまま」
「ドキュメントがどこにあるかわからないので、毎回 Slack で聞く」
これはドキュメントをコードから切り離した場所に置いていることが原因のひとつだ。
コードが変わればドキュメントも変わるべきなのに、更新する場所が別々だと同期が取れなくなる。これを解決するアプローチが Docs as Code であり、Backstage の TechDocs はその仕組みをサポートするツールだ。
Docs as Code とは
ドキュメントをコードと同じツール・プロセスで管理する考え方。
コードと同じリポジトリに docs/ を置く
↓
コードを変更するときにドキュメントも一緒にレビューする
↓
マージされたらドキュメントが自動で公開されるConfluence / Notion(コードとは別の場所) → リポジトリ内の Markdown
手動で更新を思い出す → PR に含める(コードレビューと同時)
「最終更新:誰か・いつか」が不明 → git log で誰がいつ変更したか追跡可能
バージョン管理なし → ブランチ・タグと連動
TechDocs の仕組み
Backstage の TechDocs は、リポジトリ内の Markdown を mkdocs でビルドして Backstage 上に表示する機能。
リポジトリ
├── catalog-info.yaml ← "このディレクトリに mkdocs.yml がある" と宣言
├── mkdocs.yml ← ナビゲーション・プラグイン設定
└── docs/
├── index.md
├── architecture.md
└── runbook.md
↓
Backstage の「Docs」タブで閲覧可能最小構成のセットアップ
catalog-info.yaml に1行追加:
metadata:
annotations:
backstage.io/techdocs-ref: dir:. # mkdocs.yml があるディレクトリmkdocs.yml:
site_name: my-service
docs_dir: docs
nav:
- ホーム: index.md
- アーキテクチャ: architecture.md
- Runbook: runbook.md
plugins:
- techdocs-core既存の README を流用する場合:
mkdir docs
cp README.md docs/index.mdREADME がある時点で、ほぼコスト0で TechDocs が動く。
既存リポジトリへの展開方法
すでに複数のリポジトリがある場合、一度に全部対応しようとすると挫折する。段階的に進めるのが現実的。
Phase 1: アクティブなリポジトリに絞って対応
① アクティブ × ドキュメント需要が高い → 最優先
② アクティブ × README はある → catalog-info.yaml + mkdocs.yml を追加
③ 非アクティブ → 後回しPhase 2: パイロットリポジトリで型を作る
1本だけ完成形を作り、PR として共有する。「これを真似して追加してください」と各チームに依頼するのが最も省力。
追加するファイルは3点:
catalog-info.yaml ← 新規
mkdocs.yml ← 新規
docs/index.md ← README.md のコピーでOKPhase 3: GitHub Provider で自動スキャン
全リポジトリに `catalog-info.yaml` が揃ったら、手動登録をやめる。
# app-config.yaml
catalog:
providers:
github:
your-org:
organization: your-org
catalogPath: '/catalog-info.yaml'
schedule:
frequency: { minutes: 30 }以降は `catalog-info.yaml` を置いたリポジトリが自動的に Backstage に登録される。
ドキュメントの「鮮度」を保つ仕組みを作る
PR テンプレートにドキュメント更新を含める
`.github/pull_request_template.md` に以下を追加:
## チェックリスト
- [ ] テスト追加・更新済み
- [ ] docs/ の更新が必要な場合は更新済み「ドキュメントを更新したか」をレビューの一部にすることで、更新漏れを減らせる。
CI でドキュメントビルドのチェックを追加
# .github/workflows/docs.yml
on: [pull_request]
jobs:
docs-check:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- run: pip install mkdocs-techdocs-core
- run: mkdocs build --strict # ビルドエラーを CI で検知本番運用:TechDocs を S3 にホストする
ローカルビルドはすべての表示時に Backstage サーバーがドキュメントをビルドするため、リポジトリ数が増えると重くなる。本番では CI でビルドして S3 などに保存する構成が必要。
コードが main にマージ
↓
CI が techdocs build を実行
↓
ビルド済みドキュメントを S3 に publish
↓
Backstage は S3 からドキュメントを読み込む# app-config.yaml(本番向け)
techdocs:
builder: external
publisher:
type: awsS3
awsS3:
bucketName: your-techdocs-bucket
region: ap-northeast-1# .github/workflows/techdocs.yml
- name: TechDocs ビルド & 発行
run: |
npx @techdocs/cli generate --no-docker
npx @techdocs/cli publish \
--publisher-type awsS3 \
--storage-name your-techdocs-bucket \
--entity default/Component/your-serviceConfluence / Notion との使い分け
「既存の Confluence を全部捨てるのか?」とよく聞かれるが、その必要はない。
サービスの仕様・アーキテクチャ・Runbook → TechDocs(リポジトリに近い)
組織のルール・会議録・企画書 → Confluence / Notion
API リファレンス → OpenAPI + Backstage
コードと密結合したドキュメント(「このサービスの構成はこう」「この API の使い方」「障害時の手順」)を TechDocs に移行するのが効果的。
まとめ
Docs as Code の本質は「ドキュメントをコードと同じ場所に置いて、同じプロセスで更新する」こと。
TechDocs はその仕組みをサポートするツールで、`catalog-info.yaml` に1行追加するだけで始められる。まずは README をそのまま `docs/index.md` にコピーするだけで第一歩になる。
「ドキュメントが古い問題」を構造的に解決したい場合、Docs as Code は有効なアプローチだ。