GitHub初心者ガイド - バージョン管理の基礎から実践まで

特別編：Docs-as-Code - GitHubをドキュメント管理・ナレッジ基盤として使う

学習目標

この章を読み終える頃には、以下のことができるようになります：

  • GitHub を「コード」だけでなく「文書・意思決定・運用手順」の管理基盤として使う目的とメリットを説明できる。
  • docs/ 配下に「探せる」文書を置くための最小構成（ディレクトリ設計と命名）を設計できる。
  • 文書変更を Issue と Pull Request で回す最小フロー（起票→改訂→レビュー→マージ→履歴化）を、手順として実行できる。
  • README / docs / Wiki / Issues / Discussions / Projects の使い分け基準を持てる。

Docs-as-Code とは

Docs-as-Code は、ドキュメント（仕様・運用手順・ナレッジなど）をコードと同じように Git で履歴管理 し、Pull Request でレビュー して品質を維持する考え方です。

この運用にすると、次の点が実務上のメリットになります。

  • 変更理由（Issue）と変更内容（PR）がセットで残るため、後から根拠を追えます。
  • レビューの「観点」が揃い、属人化しにくくなります。
  • 「最新版がどれか分からない」「誰が直すのか不明」などの事故を減らせます。

この章では、非エンジニアも含めて運用できるように、最小セットに絞って整理します。

推奨ディレクトリ構成（docs/ の最小セット）

「どこに何を書くか」を最初に決めておくと、文書が増えても破綻しにくくなります。最小構成の例は次のとおりです。

docs/
├── index.md               # ポータル（目次・検索導線）
├── templates/             # 文書テンプレ（ADR/議事録/設計/Runbook）
├── adr/                   # 意思決定ログ（ADR）
├── meeting-notes/         # 議事録
├── design/                # 設計書（仕様・設計）
└── runbook/               # 運用手順（Runbook）

ポイントは次の 3 点です。

  • index.md を必ず置く：最初に見る場所を 1 つに固定し、そこから各文書に移動できる状態にします。
  • 文書タイプで分類する：議事録・設計・運用手順・決定ログは目的が違うため、分けたほうが探しやすくなります。
  • テンプレを同じ場所に置く：書き方を統一し、レビュー時の観点が揃います。

実際にコピーして使えるサンプルは、リポジトリの examples/ に置いています。

  • examples/：https://github.com/itdojp/github-guide-for-beginners-book/tree/main/examples

大きなファイル・成果物の置き場（設計指針）

文書運用を本格化すると、PDF・画像・動画・ビルド成果物など「大きなファイル」が増えやすくなります。Git（履歴管理）に何でも入れると、リポジトリが肥大化して運用コストが上がります。

ここでは、初心者が判断しやすいように「入れる/入れない」の基準と代替案を整理します。

Gitに入れる/入れない（判断基準）

対象 Git（履歴管理） 推奨の置き場（例） 理由
Markdownなどの本文 入れる docs/ 差分が追いやすい
小さな画像（図解など） 条件付きで入れる docs/assets/ 文書と一体で管理したい
生成物（dist/、ビルド成果物） 入れない Releases / Packages 再生成できるなら履歴に不要
大きなバイナリ（動画・巨大PDFなど） 原則入れない LFS / 外部ストレージ 履歴が肥大化しやすい

代表的な置き場（使い分け）

  • Git LFS：大きなファイルも Git で管理したい場合の選択肢（ただし運用・容量の前提が増えます）
  • Releases のアセット：配布物（PDF、成果物ZIPなど）を「版」として公開したい場合
  • Packages：ライブラリ/コンテナなどの配布を前提にする場合
  • 外部ストレージ：容量が大きい・更新頻度が高い場合（Git には参照リンクだけ残す）

アンチパターン（避ける）

  • 生成物（dist/）や巨大ZIPをそのままコミットする
  • 画像/動画を無制限に追加して、履歴が肥大化する

サンプル構成（docs/ + assets/）は examples/ に用意しています。

文書のライフサイクル（作成→レビュー→改訂→廃止）

文書は「書いて終わり」ではなく、次の流れで保守する前提で設計します。

  1. 作成：目的（何のための文書か）と対象（誰向けか）を先に決めます。
  2. レビュー：Pull Request で「読者が迷わないか」「誤解しないか」を確認します。
  3. 改訂：変更理由（Issue）と一緒に履歴として残します。
  4. 廃止：古くなった文書は削除ではなく「廃止」を明記し、代替への導線を残します。

廃止の例：文書の冒頭に「この文書は廃止しました。後継は〜」と書き、リンクを張ります。

文書タイプとテンプレ（最小 4 種）

ここでは、混在しやすい文書を 4 種類に分けて扱います。

1) ADR（意思決定ログ）

「なぜそう決めたか」を残すための文書です。設計が変わっても、意思決定の背景は資産になります。

  • 例：採用技術、運用方針、外部公開範囲、レビュー体制

2) 議事録

「誰が」「何を」「いつまでに」を残す文書です。議論の過程を追えるようにします。

3) 設計書

仕様・制約・想定利用者・エラーケースなどを整理する文書です。実装より先に「合意」を作る用途で使います。

4) Runbook（運用手順）

障害対応・定常作業・リリース手順など、「手順として再現できる形」に落とす文書です。

テンプレのサンプルは examples/docs-as-code/docs/templates/ に置いています。

情報設計（検索・索引・タグ付け）

GitHub は「置くだけ」だと、検索できない倉庫になりがちです。最小の設計として、次の 3 点を揃えると運用しやすくなります。

1) README を入口（ポータル）にする

README には、詳細本文を増やすのではなく、最短導線（入口） と 主要リンク を置きます。

README のひな型は examples/ に用意しています。

2) docs/index.md を索引（目次）にする

docs 配下の入口（docs/index.md）に、カテゴリ別リンクをまとめて「探せる状態」を作ります。

3) ラベルを「情報分類」として設計する

Issue/Project のラベル体系は、タスク管理だけでなく 情報分類 としても使えます。ラベルを増やしすぎないためのガイドは、第8章も参照してください。

GitHub の各機能の使い分け（迷ったらここ）

文書管理は、置き場所が曖昧だと重複・分散が発生します。最初に「箱の使い分け」を決めてください。

置き場所 主目的 書く内容（例） 避けたい運用（アンチパターン）
README 入口・最短導線 目的、使い方の最短手順、主要リンク README に詳細手順を増やし続ける
docs/ 版管理する本文 仕様、運用手順、設計、ナレッジ 同じ内容を README と二重管理する
Wiki 任意（採用時のみ） 一時情報、編集しやすい資料 docs/ と重複する恒久情報を置く
Issues 依頼・議論・決定 問題、やること、合意事項、決定ログ 「決めたこと」を docs に反映しない
Discussions Q&A・アイデア 質問、相談、アイデア出し 仕様確定やタスク管理まで混ぜる
Projects 進捗の見える化 ステータス、優先度、期限 本文（仕様）を Projects 側に書く

例：Issue で決めて docs に反映する（最小フロー）

  1. Issue を作成し、「何を変えるか」「完了条件」を書きます。
  2. Issue を起点に Pull Request を作り、docs を改訂します。
  3. レビューで合意したらマージし、Issue をクローズします。

「決定」は Issue に残し、「決定の結果（最新版）」は docs に置く、と分けると整理しやすくなります。

“迷ったらここ”チェックリスト

  • 読者が最初に見るべき入口か？ → README
  • 版管理して更新したい本文か？ → docs/
  • 「決める・やる」ためのタスクか？ → Issues
  • まだ結論が出ていない相談や Q&A か？ → Discussions
  • 進捗を見える化したいか？ → Projects

実習：文書を Pull Request で改訂して履歴化する

この実習のゴールは、「文書変更を Issue と Pull Request で回す」体験を 1 周することです。

手順（非エンジニア向け：ブラウザ中心）

  1. リポジトリに docs/ を作り、docs/index.md を追加します。
  2. docs/templates/ を作り、テンプレを追加します。
  3. 変更理由として Issue を作成し、目的と完了条件を書きます。
  4. ブラウザの編集機能でブランチを作成し、Pull Request を作ります。
  5. レビューを受けて修正し、マージします。

Issue と Pull Request の基本操作は、以下の章も参照してください。

  • 第7章（ブランチ/Pull Request）：/github-guide-for-beginners-book/chapters/chapter-branch-operations/
  • Issue / Projects：/github-guide-for-beginners-book/chapters/chapter-issue-management/

手順（エンジニア向け：ローカルで Git を使う）

mkdir -p docs/templates
git switch -c docs/add-templates
git add docs/
git commit -m "docs: add templates"
git push -u origin docs/add-templates

その後、GitHub 上で Pull Request を作成してレビュー→マージします。

品質ゲートとAI支援（任意）

文書は、リンク切れや表記ゆれが増えると「読めるが信用できない状態」になりやすいです。最低限の自動チェック（品質ゲート）を入れておくと、運用の安定性が上がります。

  • docs品質ゲート（例）：.github/workflows/docs-quality-gate.yml
  • ローカル実行（例）：npm run docs:quality-gate

また、AI 支援を使う場合は、機密情報の取り扱いと検証観点をルール化しておくと、事故を減らせます。

  • AI利用ポリシー（テンプレ）：https://github.com/itdojp/github-guide-for-beginners-book/blob/main/AI_USAGE_POLICY.md

関連する章：

  • GitHub Actions：/github-guide-for-beginners-book/chapters/chapter-github-actions/

まとめ

  • Docs-as-Code は「文書を Pull Request でレビューして保守する」ための運用です。
  • docs/ の最小構成（index + 分類 + テンプレ）を決めると、文書が増えても破綻しにくくなります。
  • 置き場所（README/docs/Issues など）の使い分け基準を決め、二重管理を避けることが重要です。

次の一手（非エンジニア向け：3〜4章で体験する）

非エンジニア向けの最短ルートでは、次の順で「文書をPRで回す」体験まで到達することを目標にします。

  1. この章の実習を 1 周する（Issue → PR → レビュー → マージ）
  2. 第8章（Issue/Projects）で、文書変更の Issue を起票し、優先度やラベルで整理する
  3. 第7章（Pull Request）で、PRテンプレとレビュー運用（CODEOWNERS含む）を確認し、実際にマージまで行う
  4. 必要に応じて、第9章（GitHub Actions）で Pages 公開の導線を組み込む

更新運用（四半期点検など）の方針は UPDATE_POLICY.md を参照してください。

Edit this page on GitHub