改善提案 Issue 一覧（GitHub初心者ガイド / github-guide-for-beginners-book）

[ootakazuhiko]

運用前提：

• 目的：エンジニア/非エンジニア双方が、AI時代に「文書＋プロジェクト＋コード」をGitHubで管理できる“礎”を作る
• 方針：追加章・テンプレ整備・自動化・ガバナンスを、章立てとサンプル実装（examples/ や .github/）で提供する

---

[P0] Docs-as-Code を主役にした章（または Part）を追加する

• Labels: enhancement, docs, curriculum, non-engineer
• Scope: src/ に新章追加 + 目次更新 + examples/ 追加

背景/課題

• 「文書管理」をGitHubで行う場合の情報設計（どこに何を置くか）と運用（Issue/PRで回す）が体系化されていない。
• 非エンジニアが「どこから着手すべきか」が読み取りにくい。

提案

• 新章案：「GitHubをドキュメント管理・ナレッジ基盤として使う」
  • docs/ ディレクトリ設計（情報アーキテクチャ、命名、階層、索引）
  • 文書のライフサイクル（作成→レビュー→改訂→廃止）
  • 意思決定ログ（ADR）・議事録・運用手順（Runbook）・設計書の扱い
  • “文書変更もPRでレビューする”運用の最小セット

タスク

• 章のアウトライン作成（学習目標・用語・実習）（PR Issue #142 P0: Docs-as-Code章 + 使い分けガイド + examples追加 #144）
• docs/ 配下の推奨構成例を examples/ に追加（PR Issue #142 P0: Docs-as-Code章 + 使い分けガイド + examples追加 #144）
• 「文書の種類別テンプレ」ひな型を追加（ADR/議事録/設計/Runbook）（PR Issue #142 P0: Docs-as-Code章 + 使い分けガイド + examples追加 #144）
• 目次と「読み方の目安」に“非エンジニア向け導線”を追加（PR Issue #142 P0: Docs-as-Code章 + 使い分けガイド + examples追加 #144）

受け入れ基準（DoD）

• 章の実習で「文書をPRで改訂→レビュー→マージ」まで完走できる（PR Issue #142 P0: Docs-as-Code章 + 使い分けガイド + examples追加 #144）
• docs/ 配下の推奨構成が examples/ と一致している（PR Issue #142 P0: Docs-as-Code章 + 使い分けガイド + examples追加 #144）

---

[P0] 「README / docs / Wiki / Issues / Discussions / Projects」の使い分けガイドを追加する

• Labels: enhancement, docs, governance
• Scope: はじめに or 新章内の節 + 付録（チートシート）

背景/課題

• GitHubの各機能が“何のための箱か”が曖昧だと、情報が分散・重複しやすい。

提案

• 1ページで判断できる「置き場所の意思決定表」を追加
  • README: 入口・目的・最短導線
  • docs/: 版管理する本文
  • Wiki:（採用する場合の）運用ルールと禁止事項
  • Issues: 依頼・議論・決定のログ
  • Discussions: Q&A/アイデア出し/周知
  • Projects: 進捗の見える化

タスク

• 使い分け表（判断基準、例、アンチパターン）作成（PR Issue #142 P0: Docs-as-Code章 + 使い分けガイド + examples追加 #144）
• 例：同じテーマを「Issueで決め、docsに反映する」流れを記述（PR Issue #142 P0: Docs-as-Code章 + 使い分けガイド + examples追加 #144）
• “迷ったらここ”チェックリスト追加（PR Issue #142 P0: Docs-as-Code章 + 使い分けガイド + examples追加 #144）

DoD

• 使い分け表により、同一情報の二重管理を避ける指針が明文化されている（PR Issue #142 P0: Docs-as-Code章 + 使い分けガイド + examples追加 #144）

---

[P0] Issue Forms（YAML）と PRテンプレを標準装備として追加する

• Labels: enhancement, workflow, templates, docs
• Scope: .github/ISSUE_TEMPLATE/* , .github/PULL_REQUEST_TEMPLATE* , 書籍該当節

背景/課題

• 入力品質が人に依存すると、AI支援で生成されたIssue/PRがブレやすい。
• トリアージ（分類・優先度付け）が属人化する。

提案

• Issue Forms を用途別に用意（例：バグ/改善/文書/相談）
• PRテンプレで「目的・変更点・影響・検証・ロールバック」を固定

タスク

• bug_report.yml / feature_request.yml / docs_change.yml / question.yml を追加（PR Issue #142 P0: テンプレ（Issue/PR）+ docs品質ゲートを追加 #143）
• PULL_REQUEST_TEMPLATE.md を追加（複数テンプレ運用も検討）（PR Issue #142 P0: テンプレ（Issue/PR）+ docs品質ゲートを追加 #143）
• 書籍に「テンプレ導入の効果」「最小項目」「アンチパターン」を追記（PR Issue #142 P0: テンプレ（Issue/PR）+ docs品質ゲートを追加 #143）
• examples/ にテンプレ運用例（サンプルIssue/PR）を追加（PR Issue #142 P0: Docs-as-Code章 + 使い分けガイド + examples追加 #144）

DoD

• “文書変更”Issueが必須項目を満たさないと起票しづらい状態になっている（PR Issue #142 P0: テンプレ（Issue/PR）+ docs品質ゲートを追加 #143）
• PR本文がテンプレで統一され、レビュー観点が揃う（PR Issue #142 P0: テンプレ（Issue/PR）+ docs品質ゲートを追加 #143）

---

[P0] CODEOWNERS を使ったレビュー責任の割当（特に docs/）を解説・実装する

• Labels: enhancement, governance, review
• Scope: CODEOWNERS 追加 + 書籍（PR/セキュリティ/運用）節

背景/課題

• 「誰がレビュー責任を持つか」が曖昧だと、文書が放置されるか、レビューが詰まる。

提案

• docs/ 配下は文書オーナー（職能）に自動レビュー要求が飛ぶ設計を提示
• 章内に「責務分界（編集者/レビューア/承認者）」を明記

タスク

• CODEOWNERS のひな型を追加（docs/ と src/ で担当を分ける例）（PR Issue #142 P0: テンプレ（Issue/PR）+ docs品質ゲートを追加 #143）
• “レビューが詰まる時の対処（代替オーナー/ローテ）”を追記（PR Issue #142 P0: テンプレ（Issue/PR）+ docs品質ゲートを追加 #143）
• ブランチ保護（必須レビュー・必須チェック）との組合せを説明（PR Issue #142 P0: テンプレ（Issue/PR）+ docs品質ゲートを追加 #143）

DoD

• docs/ 変更PRで、レビュー責任の割当が自動化される運用例が提示されている（PR Issue #142 P0: テンプレ（Issue/PR）+ docs品質ゲートを追加 #143）

---

[P0] ドキュメント品質ゲート（lint/link check/表記ゆれ）を Actions で追加する

• Labels: enhancement, automation, docs, quality
• Scope: .github/workflows/docs-ci.yml + 書籍 Actions章の追記 + examples/

背景/課題

• 文書は“壊れたリンク/表記ゆれ/構造崩れ”が増えると信用を失う。
• AI生成文書は特に誤リンク・冗長・不整合が入りやすい。

提案

• docs/ 変更時に以下を自動実行
  • Markdown lint
  • リンク切れチェック
  • 表記ルール（用語集）チェック（可能なら）
• PRに結果をフィードバック

タスク

• docs-ci ワークフロー追加（トリガ: docs/ 配下変更）（PR Issue #142 P0: テンプレ（Issue/PR）+ docs品質ゲートを追加 #143: .github/workflows/docs-quality-gate.yml）
• ローカルでも同じチェックが回る手順（npm scripts等）を記載（PR Issue #142 P0: テンプレ（Issue/PR）+ docs品質ゲートを追加 #143）
• 章内に「最小の品質ゲート」と「やりすぎない範囲」を追記（PR Issue #142 P0: テンプレ（Issue/PR）+ docs品質ゲートを追加 #143）

DoD

• docs/ の変更PRで自動チェックが走り、失敗理由が明確に出る（PR Issue #142 P0: テンプレ（Issue/PR）+ docs品質ゲートを追加 #143）

---

[P1] “ドキュメントをPagesで公開する”を文書管理の導線として再設計する

• Labels: enhancement, docs, publishing
• Scope: Actions章 / トラブルシュート章 / 新章（Docs-as-Code）へのクロスリンク

背景/課題

• Pages デプロイの例があっても「何を公開対象にするか」「公開/非公開の境界」が設計されないと運用に乗らない。

提案

• 公開対象（外部公開docs vs 内部用runbook）を分ける設計パターンを追加
• PRプレビュー（可能なら）を“文書レビュー”の一部に組み込む

タスク

• 公開範囲のモデル（public docs / private docs / internal）を追記（PR Issue #142 P1: Pages公開導線の整理 + AI利用ポリシー #145）
• docs/→build→Pages の推奨ディレクトリ構成を統一（PR Issue #142 P1: Pages公開導線の整理 + AI利用ポリシー #145）
• トラブルシュート章に“文書公開運用”の観点（よくあるミス）を追記（PR Issue #142 P1: Pages公開導線の整理 + AI利用ポリシー #145）

DoD

• 「文書を作る→PRレビュー→公開」までが、1つの学習導線として接続される（PR Issue #142 P1: Pages公開導線の整理 + AI利用ポリシー #145）

---

[P1] AI時代の運用規約（AI利用ポリシー / 検証責任 / 機密入力）を追加する

• Labels: enhancement, ai, governance, security
• Scope: 新節（セキュリティ or 運用） + サンプル規約ファイル

背景/課題

• AI支援を前提にすると、生成物の検証責任・機密入力・著作権/ライセンス・ログ扱いが曖昧になりやすい。

提案

• リポジトリに置く運用規約例を提示（例：AI_USAGE_POLICY.md）
  • してよいこと／だめなこと
  • 機密・個人情報の入力禁止
  • 生成物の検証責任はPR提出者にある
  • 引用・出典・ライセンス確認の手順
• Copilot等の設定（ポリシー概念）を“運用の一部”として言及

タスク

• 規約テンプレ（最小版）作成（PR Issue #142 P1: Pages公開導線の整理 + AI利用ポリシー #145: AI_USAGE_POLICY.md）
• PRテンプレに「AI支援の有無」「検証内容」を追記（任意でも可）（PR Issue #142 P0: テンプレ（Issue/PR）+ docs品質ゲートを追加 #143）
• “AIの誤りパターン”チェックリスト（リンク/事実/設定/セキュリティ）を追加（PR Issue #142 P1: Pages公開導線の整理 + AI利用ポリシー #145）

DoD

• AI利用時の責務と禁止事項が、リポジトリに残る形で提示されている（PR Issue #142 P1: Pages公開導線の整理 + AI利用ポリシー #145）

---

[P1] 非エンジニア向け「最短ルート（文書・タスク管理）」の読み進めガイドを追加する

• Labels: enhancement, onboarding, non-engineer
• Scope: はじめに（読み方の目安）+ 各章冒頭の導線

背景/課題

• 対象読者に非エンジニアが含まれているが、最短ルートが明示されていないと離脱する。

提案

• “非エンジニア向け学習ルート”を明文化
  • リポジトリ作成 → Markdown → Issue/Projects → PRによる文書改訂 → Pages公開（必要なら）
• 各章に「非エンジニアならここだけ」枠を追加

タスク

• 読み方の目安に “Non-Engineer Track” 追加（PR Issue #142 P0: Docs-as-Code章 + 使い分けガイド + examples追加 #144）
• 各章末に次の一手（文書運用に繋がる課題）を追加（PR Issue #142 P2: 情報設計テンプレと保守性（更新/リンクチェック）を追加 #147）

DoD

• 非エンジニアが3〜4章程度で「文書をGitHubで回す」体験まで到達できる（PR Issue #142 P2: 情報設計テンプレと保守性（更新/リンクチェック）を追加 #147）

---

[P2] 付録Aのコマンドを現代的な推奨（switch/restore）に寄せ、本文と整合させる

• Labels: enhancement, docs, consistency
• Scope: appendix-git-commands-reference の更新

背景/課題

• 参照用付録は“推奨形”に寄せないと、学習者が古い書き方をコピーし続ける。

提案

• checkout を「切替: switch」「復元: restore」に分離して提示
• “歴史的事情で checkout もある”は注記に落とす

タスク

• 復元系の例を git restore に置換（PR Issue #142 P2: 付録Aをswitch/restoreに統一 #146）
• ブランチ切替の例を git switch に統一（PR Issue #142 P2: 付録Aをswitch/restoreに統一 #146）
• 章中のコマンド例と矛盾がないか点検（PR Issue #142 P2: 付録Aをswitch/restoreに統一 #146 + PR Issue #142 P1: Pages公開導線の整理 + AI利用ポリシー #145）

DoD

• 付録のコマンドが「推奨形」で統一され、本文と矛盾しない（PR Issue #142 P2: 付録Aをswitch/restoreに統一 #146 + PR Issue #142 P1: Pages公開導線の整理 + AI利用ポリシー #145）

---

[P2] 大きなファイル・バイナリ・成果物の置き場（LFS/Release/Packages）の設計指針を追加する

• Labels: enhancement, docs, repo-management
• Scope: 新節（リポジトリ設計 or 高度活用）+ examples/

背景/課題

• 文書管理を本格化するとPDF/画像/動画などが増え、repo肥大・履歴破綻が起きやすい。

提案

• “Gitに入れる/入れない”基準と代替案を提示
  • LFS
  • Releases のアセット
  • Packages
  • 外部ストレージ（参照だけをGitで管理）

タスク

• 判断基準（サイズ/更新頻度/差分性）を追記（PR Issue #142 P2: 情報設計テンプレと保守性（更新/リンクチェック）を追加 #147）
• サンプル構成（docs/ + assets/）の例を追加（PR Issue #142 P2: 情報設計テンプレと保守性（更新/リンクチェック）を追加 #147）
• アンチパターン（巨大バイナリを直コミット等）を明記（PR Issue #142 P2: 情報設計テンプレと保守性（更新/リンクチェック）を追加 #147）

DoD

• 文書管理で詰まりやすい“容量問題”の回避策が具体例付きで示されている（PR Issue #142 P2: 情報設計テンプレと保守性（更新/リンクチェック）を追加 #147）

---

[P2] 情報設計（検索・索引・タグ付け）の運用を追加する

• Labels: enhancement, docs, knowledge-management
• Scope: Docs-as-Code章 / Issue管理章 への追記

背景/課題

• GitHubは置くだけだと“検索不能な倉庫”になる。索引設計が必要。

提案

• README をポータル化（目次・主要リンク・運用ルール）
• docs/ に index を置く（カテゴリ別リンク）
• Issue/Project のラベル体系を“情報分類”として設計

タスク

• README ポータルのひな型追加（PR Issue #142 P2: 情報設計テンプレと保守性（更新/リンクチェック）を追加 #147: examples/templates/README-portal-template.md）
• docs/index.md のひな型追加（PR Issue #142 P2: 情報設計テンプレと保守性（更新/リンクチェック）を追加 #147: examples/templates/docs-index-template.md）
• ラベル設計ガイド（命名規則・粒度・増えすぎ対策）追記（PR Issue #142 P2: 情報設計テンプレと保守性（更新/リンクチェック）を追加 #147）

DoD

• “探せる”状態を作るための最小設計が、テンプレとして提供されている（PR Issue #142 P2: 情報設計テンプレと保守性（更新/リンクチェック）を追加 #147）

---

[P2] 本書自体の保守性（リンク切れ検知・更新ポリシー）を整備する

• Labels: enhancement, maintenance, automation
• Scope: 本書リポジトリのCI + 運用ドキュメント

背景/課題

• UI/機能が変わるサービスを題材にする以上、更新運用を仕組みに落とさないと劣化する。

提案

• “更新ポリシー”ページを追加（更新頻度、対象、互換性）
• リンク切れチェックをCIに追加

タスク

• 更新ポリシーの明文化（例：四半期点検）（PR Issue #142 P2: 情報設計テンプレと保守性（更新/リンクチェック）を追加 #147: UPDATE_POLICY.md）
• リンクチェックCI追加（PR Issue #142 P2: 情報設計テンプレと保守性（更新/リンクチェック）を追加 #147: nav-link-check改善 + docs品質ゲート）
• 破壊的変更（UI差分等）の追記ルール策定（PR Issue #142 P2: 情報設計テンプレと保守性（更新/リンクチェック）を追加 #147: UPDATE_POLICY.md）

DoD

• 本書の品質がCIと運用ルールで維持できる状態になっている（PR Issue #142 P2: 情報設計テンプレと保守性（更新/リンクチェック）を追加 #147）

[ootakazuhiko]

進捗更新です。

• P0 のうち「Issue Forms/PRテンプレ」「CODEOWNERS」「ドキュメント品質ゲート（Actions）」は PR Issue #142 P0: テンプレ（Issue/PR）+ docs品質ゲートを追加 #143 で実装しました（マージ待ち）。
  • PR: Issue #142 P0: テンプレ（Issue/PR）+ docs品質ゲートを追加 #143
• Issue 本文のチェックリストも、上記 3 点について PR 参照つきで消し込みました。

次の着手予定（P0 残り）:

• Docs-as-Code を主役にした章（+ examples/ テンプレ）
• 「README / docs / Wiki / Issues / Discussions / Projects」使い分けガイド
• examples/ の「テンプレ運用例（サンプルIssue/PR）」

[ootakazuhiko]

進捗更新です。

• P0（Docs-as-Code章 / 使い分けガイド / examples）は PR Issue #142 P0: Docs-as-Code章 + 使い分けガイド + examples追加 #144 で対応しました（マージ待ち）。
  • PR: Issue #142 P0: Docs-as-Code章 + 使い分けガイド + examples追加 #144
• P0（Issue Forms/PRテンプレ、CODEOWNERS、ドキュメント品質ゲート）は PR Issue #142 P0: テンプレ（Issue/PR）+ docs品質ゲートを追加 #143 のままです（マージ待ち）。
  • PR: Issue #142 P0: テンプレ（Issue/PR）+ docs品質ゲートを追加 #143
• Issue 本文のチェックリストも、上記 2 PR の参照つきで消し込みました。

次の候補（P1/P2）:

• Pages 公開導線の再設計（P1）
• AI時代の運用規約（AI利用ポリシー等）（P1）
• 付録Aのコマンドを switch/restore に寄せる（P2）

[ootakazuhiko]

P0 の 2 PR（#143/#144）がマージされたため、P0 は完了状態です。

• Issue #142 P0: テンプレ（Issue/PR）+ docs品質ゲートを追加 #143（テンプレ/CODEOWNERS/Docs品質ゲート）: Issue #142 P0: テンプレ（Issue/PR）+ docs品質ゲートを追加 #143
• Issue #142 P0: Docs-as-Code章 + 使い分けガイド + examples追加 #144（Docs-as-Code章/使い分けガイド/examples）: Issue #142 P0: Docs-as-Code章 + 使い分けガイド + examples追加 #144

次の着手候補は P1（Pages導線の再設計、AI利用ポリシー、非エンジニア向け最短ルート）です。

[ootakazuhiko]

P1 対応として、Pages公開導線の整理と AI 利用ポリシー（最小版）を追加する PR を作成しました。

• PR Issue #142 P1: Pages公開導線の整理 + AI利用ポリシー #145: Issue #142 P1: Pages公開導線の整理 + AI利用ポリシー #145

Issue 本文のチェックリストも PR 参照つきで消し込みました。

[ootakazuhiko]

P2（付録Aのswitch/restore統一）対応として PR を作成しました。

• PR Issue #142 P2: 付録Aをswitch/restoreに統一 #146: Issue #142 P2: 付録Aをswitch/restoreに統一 #146

※ Docs-as-Code 章の git checkout -b は PR #145 側で git switch -c に統一済みのため、#145 を先にマージすると全体として整合します。