03.レビュー規定

このドキュメントは、本プロジェクトにおけるドキュメントの品質を維持・向上させるためのレビュープロセスに関する規則を定めます。

1. レビューの観点

ドキュメントをレビューする際は、以下の観点を総合的に確認してください。

• 明確性: 内容は対象読者にとって分かりやすいか？専門用語は適切に使われているか？
• 正確性: 技術的な記述、数値、参照情報などに誤りはないか？最新の情報に基づいているか？
• 一貫性: プロジェクトで定める用語、書式、構造が一貫して適用されているか？
• 網羅性: 説明すべき事項が過不足なく記述されているか？読者が必要とする情報が提供されているか？
• 簡潔性: 冗長な表現や不必要な情報はないか？
• 構成と構造: 情報は論理的に構成され、見出しやリストが効果的に使われているか？
• 保守性: 将来の変更や更新が容易に行えるように記述されているか？
• 準拠性: 01.基本規定 や関連するコーディング規定などの規約に準拠していること。
• 対象読者への配慮: ドキュメントの目的と対象読者に合った言葉遣いや詳細度になっているか？

2. 用語と表現の統一

ドキュメント全体の一貫性を保つため、以下の点に注意してください。

• 用語の統一:
  • プロジェクト内で定義された用語（要求仕様書の用語定義など）が一貫して使用されているかを確認します。
  • 例: 認証, 認可, セッションなど。
• 日本語表現:
  • 文法的に正しく、自然で分かりやすい日本語か。
  • 誤字脱字、不適切な句読点はないか。
  • 専門用語の乱用や、逆に説明不足な箇所はないか。
  • 文体は敬体（です・ます調）または常体（だ・である調）に統一されているか。
• 英語表記の併用:
  • コード内の識別子、API名、一般的な技術用語など、英語表記が適切な場面で正しく使用されているか。括弧書きでの補足は分かりやすいか。

3. レビューの対象

原則として、すべてのドキュメントの新規作成および重要な変更はレビューの対象となります。

• 新規作成: 新しい機能要件、設計書、開発ルールなど。
• 重要な変更:
  • 仕様や設計の根幹に関わる変更。
  • 他のドキュメントやコードに影響を与える変更。
  • 手順の大幅な変更。
• 軽微な変更:
  • タイポの修正、誤字脱字の修正、表現の微調整など、内容に影響を与えない変更はレビューを省略できます。
  • ただし、判断に迷う場合はレビューを依頼することが推奨されます。

4. レビュープロセス

ドキュメントのレビューは、GitHubのプルリクエスト(Pull Request)機能を利用して行います。

1. ブランチの作成:
   • ドキュメントの作成・編集を行う際は、05.ブランチ規定 に従って適切なブランチを作成します。
2. プルリクエストの作成:
   • 作業が完了したら、mainブランチへのマージをリクエストするプルリクエストを作成します。
   • プルリクエストの概要には、変更の目的や内容を明確に記述します。
3. レビュアーの指定:
   • 変更内容に応じて、適切なレビュアーを1名以上指定します。
   • レビュアーは、プロジェクトのリーダー、関連する機能の担当者、またはドキュメントの品質管理担当者などが考えられます。
4. レビューの実施とフィードバック:
   • レビュアーは、プルリクエストの差分を確認し、コメント機能を使ってフィードバック（質問、指摘、改善提案）を行います。
   • レビュー観点は「1. レビューの観点」に挙げた項目を基準とします。
5. 修正と再レビュー:
   • 作成者は、フィードバックを元にドキュメントを修正し、再度コミット＆プッシュします。
   • すべての指摘事項が解決されるまで、このプロセスを繰り返します。
6. 承認 (Approve):
   • レビュアーは、内容が適切であると判断した場合、プルリクエストを承認 (Approve) します。
7. マージ:
   • 1名以上のレビュアーから承認を得た後、リポジトリ管理者がプルリクエストをマージします。

5. セルフレビュー

プルリクエストを作成する前に、作成者自身で以下の点についてセルフレビューを行うことが推奨されます。

• 誤字脱字はないか。
• リンク切れは発生していないか。
• mkdocs.ymlのナビゲーションは更新されているか。（02.ナビゲーション規定 参照）
• フォーマット（見出しレベル、リスト、コードブロックなど）は適切か。
• 規定された命名規則やID体系に従っているか。

6. 重要確認項目

特に重要なレビュー項目として、以下の点を確認します。

6.1. トレーサビリティの確保

ドキュメント間の連携と追跡可能性を確保するため、以下の点を確認します。

• 要求ID:
  • IDの命名規則は 01.基本規定 に準拠しているか？
  • 要求仕様書で定義されたIDが、設計書やテスト仕様書から正しく参照されているか？
• アンカーとリンク:
  • 要求IDの定義箇所に、適切なアンカー ({ #REQ-XXX-X.X }など) が設定されているか？
  • 相互リンクは正しく機能しているか？リンク切れはないか？
• 参照関係:
  • あるドキュメントが他のどのドキュメントを参照し、または参照されているかの関係性が明確に記述されているか？

6.2. 各ドキュメントカテゴリのレビュー観点

ドキュメントの種類に応じて、以下の観点も重視します。

• 要求仕様書:
  • 要件は明確で、テスト可能で、実現可能か？
  • スコープは適切に定義されているか？
  • ユースケースは具体的で、ユーザーの視点に立っているか？
• 設計仕様書:
  • 設計は要求仕様を満たしているか？技術的な実現性は考慮されているか？
  • API仕様、データ仕様、UI/UX仕様は正確かつ網羅的か？
  • 図や説明は十分か？
• 開発ルール:
  • 開発プロセスや規約は実用的で、プロジェクトの目的に合致しているか？
• テスト仕様書:
  • テストケースは要求仕様を網羅しているか？
  • テスト手順は明確で再現可能か？