Issue #142 P2: 情報設計テンプレと保守性（更新/リンクチェック）を追加 (#147)

* feat: 運用保守と情報設計テンプレを追加（Issue #142 P2）

* fix: 表記ゆれを修正

Author: ootakazuhiko

.github/workflows/nav-link-check.yml

@@ -54,12 +54,24 @@ jobs:
               return paths
           def discover():
               paths=[]
+              # book-formatter系（introduction/chapters/appendices/...）
               for seg in ['introduction','chapters','appendices','afterword']:
                   d = Path('docs')/seg
                   if d.is_dir():
                       for child in sorted(d.iterdir()):
-                          if child.is_dir():
+                          if child.is_dir() and (child / 'index.md').exists():
                               paths.append(f'/{seg}/{child.name}/')
+
+              # 本リポジトリ（docs/src/**）
+              src_root = Path('docs') / 'src'
+              if src_root.is_dir():
+                  for child in sorted(src_root.iterdir()):
+                      if child.is_dir() and (child / 'index.md').exists():
+                          paths.append(f'/src/{child.name}/')
+
+              # examples（docs/examples/index.md）
+              if (Path('docs') / 'examples' / 'index.md').exists():
+                  paths.append('/examples/')
               return paths
           paths = read_nav() or discover() or ['/']
           # Always include index

UPDATE_POLICY.md

@@ -0,0 +1,52 @@
+# 更新ポリシー（テンプレ）
+
+この文書は、本書（GitHub初心者ガイド）を継続的に保守するための「更新方針」と「更新手順」を定義します。
+
+## 目的
+
+- GitHub の UI / 機能変更によって、本書の説明が古くなることを前提に、更新作業を運用に落とす。
+- 読者の学習を阻害する品質劣化（リンク切れ、手順欠落、表記ゆれ）を早期に検知する。
+
+## 更新の対象範囲
+
+- 本文（`docs/src/**`）
+- 実習サンプル（`examples/**`）
+- CI（品質ゲート・リンクチェック）やテンプレ（`.github/**`）
+
+## 更新頻度（推奨）
+
+- **四半期に1回**（例：3か月に1回）、次の観点で棚卸しします。
+  - UI 手順のスクリーンショットや操作導線が現行 UI と矛盾していないか
+  - 章末の手順・コマンドが「推奨形」になっているか
+  - リンク切れ、参照先の移動がないか
+
+## 変更管理の原則
+
+- 変更理由は Issue に残し、変更内容は Pull Request でレビューします（Docs-as-Code）。
+- 影響が大きい更新は、小さな PR に分割してレビュー可能性を優先します。
+
+## 破壊的変更（UI差分・機能差分）が発生したときの扱い
+
+GitHub 側の UI や挙動が変わり、手順がそのままでは成立しなくなった場合は、次のルールで扱います。
+
+1. **Issue を起票**し、「どこが」「なぜ」成立しないかを記録します（スクリーンショットやログがあるとよい）。
+2. 本文は、断定ではなく **前提条件と確認ポイント** を追加します（例：「画面が異なる場合は Settings → … を探す」）。
+3. 章内で同様の導線が複数ある場合は、1か所だけ直して終わらせず、関連章も点検します。
+
+## 品質ゲート（CI）
+
+本書は、最低限の自動チェックで品質を維持します。
+
+- PR時（差分 docs のみ）：
+  - `.github/workflows/docs-quality-gate.yml`
+  - Markdown lint + 内部ファイルリンクチェック
+- 定期（公開ページの到達確認）：
+  - `.github/workflows/nav-link-check.yml`
+
+## 更新作業のチェックリスト（例）
+
+- [ ] 関連 Issue に「現象」「影響範囲」「完了条件（DoD）」がある
+- [ ] 章の手順が省略されていない（前提条件・注意事項がある）
+- [ ] 章内のリンクが有効（内部リンク/公開ページ）
+- [ ] `npm run docs:quality-gate` が通る
+

docs/examples/index.md

@@ -18,9 +18,18 @@ title: 実習サンプル（examples/）
 - 推奨ディレクトリ構成（`docs/`）
 - 文書テンプレ（ADR/議事録/設計/Runbook）
 - Issue/PR のサンプル文面
+- `docs/assets/`（小さな添付・図解の置き場）
 
 該当パス：`examples/docs-as-code/`
 
+### すぐ使えるテンプレ集
+
+- README（入口ポータル）
+- `docs/index.md`（文書ポータル）
+- ラベル設計（増えすぎ対策の最小セット）
+
+該当パス：`examples/templates/`
+
 ## 使い方（コピーして使う）
 
 1. `examples/` から必要なフォルダを選びます。

docs/src/chapter-docs-as-code/index.md

@@ -57,6 +57,35 @@ docs/
 
 ---
 
+## 大きなファイル・成果物の置き場（設計指針）
+
+文書運用を本格化すると、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/` に用意しています。
+
 ## 文書のライフサイクル（作成→レビュー→改訂→廃止）
 
 文書は「書いて終わり」ではなく、次の流れで保守する前提で設計します。
@@ -96,6 +125,26 @@ docs/
 
 ---
 
+## 情報設計（検索・索引・タグ付け）
+
+GitHub は「置くだけ」だと、検索できない倉庫になりがちです。最小の設計として、次の 3 点を揃えると運用しやすくなります。
+
+### 1) README を入口（ポータル）にする
+
+README には、詳細本文を増やすのではなく、**最短導線（入口）** と **主要リンク** を置きます。
+
+README のひな型は `examples/` に用意しています。
+
+### 2) docs/index.md を索引（目次）にする
+
+docs 配下の入口（`docs/index.md`）に、カテゴリ別リンクをまとめて「探せる状態」を作ります。
+
+### 3) ラベルを「情報分類」として設計する
+
+Issue/Project のラベル体系は、タスク管理だけでなく **情報分類** としても使えます。ラベルを増やしすぎないためのガイドは、第8章も参照してください。
+
+---
+
 ## GitHub の各機能の使い分け（迷ったらここ）
 
 文書管理は、置き場所が曖昧だと重複・分散が発生します。最初に「箱の使い分け」を決めてください。
@@ -178,3 +227,16 @@ git push -u origin docs/add-templates
 - 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` を参照してください。

docs/src/chapter-github-actions/index.md

@@ -806,6 +806,18 @@ jobs:
 
 次の章では、セキュリティ対策について学び、安全なGitHub利用方法を身につけます。
 
+---
+
+## 次の一手（文書公開に繋げる）
+
+Docs-as-Code の運用に「公開（Pages）」を組み込みたい場合は、次の順で進めることを推奨します。
+
+1. 公開範囲（public docs / private docs / internal）を決める
+2. Pages の公開方式を選ぶ（Deploy from a branch / GitHub Actions で build → deploy）
+3. PR を起点に文書を更新し、マージで公開版が更新される導線を作る
+
+運用方針（更新頻度・破壊的変更時の扱い）は `UPDATE_POLICY.md` を参照してください。
+
 ![PRベストプラクティスサマリー]({{ '/assets/images/diagrams/chapter08/14_pr_best_practices_summary.svg' | relative_url }})
 
 **理解度確認：**

docs/src/chapter-issue-management/index.md

@@ -207,6 +207,24 @@ GitHub上では無数のオープンソースプロジェクトが公開され
 - `needs review`：レビュー待ち
 - `blocked`：他の課題に依存
 
+### ラベル設計のガイド（増えすぎ対策）
+
+ラベルは増やしすぎると運用コストが上がり、逆に「分類できない」状態になります。初心者向けの最小指針は次のとおりです。
+
+- **軸を決める**：種類（type）/優先度（priority）/担当領域（area）など、役割が違うラベルを混ぜない
+- **プレフィックスで揃える**：例：`type: docs`、`priority: high`、`area: docs`
+- **定義を明文化する**：ラベル名だけで判断できない場合は、CONTRIBUTING などに運用ルールを書く
+- **増えすぎを防ぐ**：使われていないラベルは定期的に整理する（四半期点検など）
+
+**最小セットの例（文書運用を含む）**
+
+- 種類：`type: bug` / `type: docs` / `type: feature` / `type: question`
+- 優先度：`priority: high` / `priority: medium` / `priority: low`
+- 担当領域：`area: docs` / `area: ci` / `area: security`（必要な範囲だけ）
+- 状態：`status: in progress` / `status: needs review` / `status: blocked`
+
+※ 既存の標準ラベル（`bug` / `documentation` など）を使う運用でも問題ありません。重要なのは「粒度」と「増えすぎ対策」です。
+
 ### 貢献ガイドライン
 
 ![貢献ガイドライン]({{ '/assets/images/diagrams/chapter07/05_contribution_guidelines.svg' | relative_url }})
@@ -507,3 +525,17 @@ Done:
 □ プロジェクトボードでタスクを視覚的に管理できる  
 □ チーム開発でのIssue活用方法を理解している  
 □ 継続的な改善プロセスを実践できる
+
+---
+
+## 次の一手（文書運用に繋げる）
+
+文書運用（Docs-as-Code）に繋げる場合は、次の 2 ステップを推奨します。
+
+1. 「文書変更」の Issue を 1 件起票する（目的・完了条件を明記する）
+2. 起票した Issue を起点に PR を作成し、レビュー→マージまで完了する（第7章）
+
+参照：
+
+- Docs-as-Code：{{ '/src/chapter-docs-as-code/' | relative_url }}
+- Pull Request：{{ '/src/chapter-pull-requests/' | relative_url }}

docs/src/chapter-pull-requests/index.md

@@ -353,7 +353,7 @@ Pull Requestをマージする際には、様々な戦略があります。プ
 
 ![PR自動化ツール]({{ '/assets/images/diagrams/chapter08/08_pr_automation_tools.svg' | relative_url }})
 
-效率的なチーム開発のために、PRプロセスの一部を自動化することができます。CI/CD、自動テスト、コード品質チェックなどのツールを活用しましょう。
+効率的なチーム開発のために、PRプロセスの一部を自動化することができます。CI/CD、自動テスト、コード品質チェックなどのツールを活用しましょう。
 
 ![ブランチワークフローパターン]({{ '/assets/images/diagrams/chapter06/16_branch_workflow_patterns.svg' | relative_url }})
 
@@ -399,11 +399,24 @@ Pull Requestをマージする際には、様々な戦略があります。プ
 
 Pull Requestのメトリクスを分析することで、チームの開発効率やコード品質を継続的に改善できます。レビュー時間、マージ率、コンフリクト発生率などの指標を活用しましょう。
 
-次の章では、チーム開発に欠かせないプルリクエスト機能について詳しく学習します。
+次の章では、Issue管理とプロジェクト管理について学習します。
 
 **理解度確認：**
 □ ブランチの概念を理解し、適切に作成・切り替えができる  
 □ マージ操作により変更を安全に統合できる  
 □ 基本的なコンフリクトを自力で解決できる  
 □ ブランチを使った開発ワークフローを実践できる  
 □ 予防的なベストプラクティスを理解している
+
+---
+
+## 次の一手（文書運用に繋げる）
+
+文書運用（Docs-as-Code）を前提にする場合は、次の 1 ステップを完了させると「運用が回る状態」に近づきます。
+
+- 文書変更の PR を 1 件作成し、レビュー→マージまで完了する（Issue と紐づける）
+
+参照：
+
+- Docs-as-Code：{{ '/src/chapter-docs-as-code/' | relative_url }}
+- Issue / Projects：{{ '/src/chapter-issue-management/' | relative_url }}

examples/README.md

@@ -5,3 +5,4 @@
 ## 収録内容
 
 - `docs-as-code/`：Docs-as-Code（文書運用）の最小セット（推奨構成・テンプレ・サンプル）
+- `templates/`：README（ポータル）/ docsポータル / ラベル設計のテンプレ

examples/docs-as-code/docs/assets/README.md

@@ -0,0 +1,16 @@
+# docs/assets/（小さな添付・図解の置き場）
+
+このディレクトリは、ドキュメントと一緒にバージョン管理したい **小さな画像/添付** を置く想定です。
+
+## 置いてよいもの（例）
+
+- 図解の画像（SVG/PNG）
+- 手順書の補助画像
+- 小さなサンプルファイル（サイズが小さいもの）
+
+## 置かないほうがよいもの（例）
+
+- 動画や巨大PDFなど、容量が大きいファイル
+- `dist/` などのビルド成果物（再生成できるもの）
+
+大きな成果物は、Releases / Packages / LFS / 外部ストレージなどの選択肢を検討し、Git の履歴を肥大化させない方針を推奨します。

examples/templates/README-portal-template.md

@@ -0,0 +1,51 @@
+# README（ポータル）テンプレ
+
+このテンプレは、README を「入口（ポータル）」として機能させるための最小構成です。  
+目的は、詳細本文を README に溜めず、`docs/` に誘導して二重管理を避けることです。
+
+---
+
+# （プロジェクト名）
+
+## 目的（このリポジトリは何か）
+
+- （例）チーム内の運用手順と意思決定ログを一元管理する
+
+## 最短導線（Quick Start）
+
+1. **まず読む**：`docs/index.md`（文書ポータル）
+2. **次にやる**：`docs/templates/` のテンプレで文書を作成する
+3. **困ったら**：Issue を起票する（`type: question` など）
+
+## どこに何を書くか（置き場所）
+
+- README：入口・最短導線・主要リンク
+- `docs/`：版管理する本文（仕様・運用手順・ナレッジ）
+- Issues：決める/やる（議論とタスク）
+- Projects：進捗の見える化
+- Discussions：Q&A、相談（任意）
+
+## 文書ポータル
+
+- `docs/index.md`
+
+## 運用ルール（最小セット）
+
+- 文書の追加・更新は Pull Request でレビューする
+- Issue に「目的」と「完了条件（DoD）」を書く
+- 廃止した文書は削除ではなく「廃止」と明記し、後継リンクを残す
+
+## ラベル（推奨）
+
+- `type:` / `priority:` / `area:` / `status:` など、軸を分けて運用する
+- 例：`type: docs`、`priority: medium`、`area: docs`
+
+## AI支援（任意）
+
+- AI を使う場合は、機密入力の禁止と検証観点を守る  
+  - `AI_USAGE_POLICY.md`
+
+## ライセンス
+
+- （例）MIT / CC BY-NC-SA など
+