ドキュメントレビュー

意図

ドキュメントが docs/DOCUMENTATION.md の方針に沿っているかを体系的にレビューし、改善点を特定する。 ドキュメントは仕様の一部であり、その品質はライブラリの使いやすさに直結する。

レビューは 双方向 である。ドキュメントが方針に合っているかだけでなく、方針がドキュメントの実態に合っているかも問う。

レビュー手順

1. 対象の特定

引数でファイルパスやパッケージ名が指定されていればそれを対象にする。 指定がなければ、以下の優先順で対象を決める:

• •直近の変更（git diff）に関連するドキュメント
• •指定がなければ全体レビュー

2. DOCUMENTATION.md の方針を読む

docs/DOCUMENTATION.md を読み、現在の方針・テンプレートを確認する。

3. チェック観点

テンプレート準拠

パッケージ README:

• •セクション順序: タイトル → (Philosophy) → Installation → Usage → API → (Module Structure)
• •必須セクション（Installation, Usage, API）が揃っているか
• •API セクションの形式（関数シグネチャ → インターフェース → 説明）

Showcase README:

• •セクション順序: タイトル → 機能 → 実装のポイント → 実行
• •「実装のポイント」がコード例付きで説明されているか
• •躓きポイントが記述されているか

情報の配置

• •API 仕様がパッケージ README にあるか（showcase README に混入していないか）
• •実装パターンが showcase README にあるか（パッケージ README に混入していないか）
• •同じ情報が複数箇所に存在していないか

実装との整合性

• •README に書かれた API が実装に存在するか
• •型シグネチャが最新か
• •使用例のコードが実際に動作するか

日英同期（ルート README）

• •README.md と README.ja.md の内容が一致しているか
• •セクション構成、コード例、順序が揃っているか

JSDoc

• •公開 API に JSDoc が付いているか
• •@param, @returns が記述されているか

方針自体の妥当性

レビューの過程で、以下のような摩擦に気づいたら記録する:

• •テンプレートに合わせると不自然になる箇所 → テンプレートの見直しが必要かもしれない
• •配置ルールで判断に迷う情報 → 配置基準が不十分かもしれない
• •同じ指摘が複数ドキュメントで繰り返される → 方針の記述が不明確かもしれない
• •テンプレートにない構造が自然に使われている → テンプレートの拡張が妥当かもしれない

これらは「ドキュメントの問題」ではなく「方針の問題」である可能性がある。

4. 報告フォーマット

対象: <ファイルパス>

方針へのフィードバック（該当する場合のみ）:

レビュー中に方針側の改善が必要だと感じた点があれば、ここに記載する。 「ドキュメントを方針に合わせるべき」か「方針をドキュメントに合わせるべき」かの判断も含める。

現時点の方針

• •実装との乖離は必ず指摘する（仕様の信頼性に直結）
• •テンプレートからの軽微な逸脱は「推奨」として報告
• •新パッケージや新 showcase 追加時は特に厳密にテンプレート準拠を確認
• •レビュー中に感じた方針への摩擦は、報告に含める（ドキュメントの問題か方針の問題かを区別する）

今後の検討事項

• •ドキュメントの自動チェック（セクション構造の lint など）
• •README から型情報を自動抽出して整合性チェック
• •JSDoc カバレッジの定量レポート
• •レビューで蓄積された方針フィードバックの定期的な振り返り