メインコンテンツへスキップ
見出し画像

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.md

    README がある時点で、ほぼコスト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 のコピーでOK

    Phase 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-service

    Confluence / 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 は有効なアプローチだ。

     
     
    社内インフラ(AWS/Terraform)を管理するしがないエンジニアです。 個人的に試してみたことだったりをつらつらと書き溜めていきます。

    あなたへのおすすめ