Status: v0 Review cadence: Monthly Reference: River-Reviewer documentation structure Related: docs/ai/issue-governance.md — Issue / Label / Milestone Governance（本ドキュメントは Doc 配置・更新ルール側、Issue 運用側は別正本）
PlanGate のドキュメント管理方針と更新ルールを定義する。
Kiro 前提の配置ではなく、River-Reviewer を参考に、公開説明ドキュメントは docs/pages/、開発・運用ドキュメントは docs/ に分ける。
このドキュメントは、次の判断を揃えるための正本である。
| Directory | Role |
|---|---|
docs/pages/ |
公開サイト・外部説明・プロダクト説明・ガイド・リファレンス |
docs/pages/explanation/ |
背景、思想、設計意図、プロダクト説明 |
docs/pages/guides/ |
導入手順、運用手順、デモ手順、ドキュメント管理方針 |
docs/pages/reference/ |
FAQ、仕様、スキーマ、用語集、参照資料 |
docs/ |
開発者向け runbook、内部運用、作業ログ、移行メモ、workflow 定義 |
docs/working/ |
TASK 単位の作業コンテキスト、レビュー記録、handoff |
docs/archive/ |
歴史的設計文書（過去バージョン設計、現行正本ではない） |
docs/pages/explanation/ に置くものdocs/pages/guides/ に置くものdocs/pages/guides/getting-started.md）docs/pages/reference/ に置くものdocs/ に置くものdocs/working/ 配下の task-specific artifacts以下の変更を行う PR では、関連ドキュメントも同じ PR で更新する。
| Change type | Required documentation update |
|---|---|
| User-facing behavior change | docs/pages/guides/ または docs/pages/reference/ を更新する |
| Product messaging change | docs/pages/explanation/product/ を更新する |
| Workflow / Gate change | docs/ の workflow 定義と公開 guide の影響を確認する |
| CLI command change | CLI reference / guide / demo script を更新する |
| Schema change | reference / schema docs / examples を更新する |
| Metrics / Eval / Keep Rate change | metrics / eval docs と product messaging の整合を確認する |
| Model Profile / Provider behavior change | model profile docs と positioning / FAQ の影響を確認する |
| Security / Privacy / Public data policy change | governance docs / FAQ / reference を更新する |
| Breaking change | migration note / release note / affected guide を更新する |
以下は原則としてドキュメント更新不要。ただし、利用者の理解に影響する場合は更新する。
ドキュメントに影響する可能性がある PR では、以下を確認する。
- [ ] User-facing behavior changed?
- [ ] Public docs under docs/pages/ need updates?
- [ ] Developer docs under docs/ need updates?
- [ ] sidebars.js needs navigation updates?
- [ ] FAQ needs a new entry or changed answer?
- [ ] Product positioning or elevator pitch changed?
- [ ] Screenshots / examples / commands are still accurate?
- [ ] Old paths or duplicated docs were removed or redirected?
公開説明ドキュメントには、先頭付近に以下の情報を置く。
> **Status**: v0 / Draft / Stable / Deprecated
> **Review cadence**: Monthly / Quarterly / On change
> **Owner**: Product / Maintainer / Engineering / Governance
短い reference ページでは Owner を省略してもよいが、Status と Review cadence は原則として残す。
| Status | Meaning |
|---|---|
Draft |
内容が検討中。外部向けに使う場合は注意する |
v0 |
初版。大きな変更が入り得る |
Stable |
現行仕様・説明として正本扱いできる |
Deprecated |
古い内容。移行先を明記する |
| Document type | Default cadence |
|---|---|
| Product messaging | Monthly |
| FAQ | Monthly |
| Demo Script | Monthly |
| Governance | Monthly |
| CLI / Schema reference | On change |
| Workflow / Hook / Eval implementation docs | On change |
| Architecture explanation | Quarterly |
| Historical / migration notes | No regular review |
| Area | Owner |
|---|---|
| Product Overview / Positioning / Elevator Pitch | Product / Maintainer |
| FAQ / Demo Script | Product / Maintainer |
| Workflow / Gate docs | Engineering / Maintainer |
| CLI / Schema reference | Engineering |
| Metrics / Eval / Keep Rate docs | Engineering / Governance |
| Documentation Management | Governance / Maintainer |
docs/working/ artifacts |
Task owner |
Product narrative の正本は以下とする。
docs/pages/explanation/product/overview.md
docs/pages/explanation/product/positioning.md
docs/pages/explanation/product/pm-po-elevator-pitch.md
README や issue でプロダクト説明を書く場合は、上記と矛盾させない。
FAQ の正本は以下とする。
docs/pages/reference/product-faq.md
導入検討時の反論・質問が増えた場合は、まず FAQ を更新する。
デモ手順の正本は以下とする。
docs/pages/guides/product-demo-script.md
CLI や workflow の変更でデモ手順が変わる場合は、必ず更新する。
ドキュメント配置・更新ルールの正本はこのファイルとする。
docs/pages/guides/governance/documentation-management.md
注記（公開ビルド実態 / 2026-06）: 現在の公開は GitHub Pages の Jekyll legacy （source:
main//docs）であり、sidebars.jsは 未参照の残骸（将来の Docusaurus 移行用の準備ファイル）です。現状の公開ナビゲーションはdocs/index.mdをトップに、jekyll-relative-linksプラグインによる.md相対リンクで構成されます （docs/_config.ymlでworking/を公開除外）。以下の sidebars.js 方針は Docusaurus 移行後に有効化する想定です。それまでsidebars.jsの更新は公開に反映 されないため、公開導線の変更はdocs/index.md（および各docs/pages/の目次）で行います。
River-Reviewer と同様、公開 docs の navigation は sidebars.js で管理する。
カテゴリは以下を基本とする。
- index
- ガイド
- リファレンス
- 解説
PlanGate では Product narrative を 解説 > プロダクト に置く。
docs/pages/ に新しい公開ページを追加した場合は、原則として sidebars.js へ追加する。
例外は以下のみ。
Migration completed (2026-05)
docs/product/は存在しない。上記テーブルに記載されていた全ファイルはdocs/pages/への移動が完了している。このセクションは履歴記録として残す。
月 1 回、以下を見直す。
docs/pages/ と docs/ の役割が混ざっていないかdocs/pages/ に集約されているかdocs/working/ が公開導線に含まれていないかsidebars.js の導線が壊れていないか古いページをすぐ削除しない場合は、先頭に以下を明記する。
> **Status**: Deprecated
> **Replacement**: `path/to/new-page.md`
以下に該当する場合は削除してよい。
意思決定や移行履歴として残す価値があるものは、削除せず保管する。
過去バージョンの設計文書など歴史的設計文書は docs/archive/ へ、
release / audit / migration logs など運用記録は docs/ 側へ移す。
この方針は以下を目的にしない。
docs/ を即時 docs/pages/ に移行することdocs/working/ を公開サイトに含めること公開説明は docs/pages/。
開発・運用・作業ログは docs/。
TASK 固有の状態は docs/working/。
User-facing change には doc update を伴わせる。 古い情報は放置せず、更新・非推奨化・削除のいずれかを選ぶ。