報告用ドキュメントレビューガイドライン
読み手に早く分かりやすく正しく伝えるための報告ドキュメントの書き方の観点が記載してある。 ドキュメントの内容に応じて必要な観点は変わるので、観点は取捨選択する。
レビュー結果の出力形式
- •総評を記載
- •観点と確認項目ごとに、指摘内容を分かりやすく記載（現状と修正提案）
- •⭐️が付いている確認項目は出力でも⭐️を付ける
- •気付いたことは省略せず指摘内容として記載
⭐️：重要度が高いと思われるもの
1. レビュー依頼 (レビューを円滑に進めるために)
レビューを依頼する際に、レビュアーに明確に伝えるべき事項。 これにより、レビューの質と時間効率が向上する。
- •ドキュメントの目的と背景を伝える
- •このドキュメントが「何を解決したいのか」「どのような背景で作成されたのか」を明確に記載する。
- •レビューのゴールを示す
- •レビュアーに何を期待するのかを伝える。
- •「〜を承認してほしい」「〜について意見がほしい」「アイデアの壁打ち相手になってほしい」など、具体的なゴールを示す。
- •重点的に見てほしい箇所があれば伝える
- •特に自信がない部分や、議論したい論点を具体的に示すことで、レビュアーがどこに注目すべきか分かりやすくなる。
2. 構成と論理展開 (分かりやすいストーリーか)
ドキュメント全体の構造や話の流れに関する観点。 読み手がストレスなく内容を理解できるかをチェックする。
- •全体像の提示
- •冒頭に、全体の要約（サマリー）や結論を記載する。
- •⭐️「これはシステム全体のどの部分の話か」など、議論対象のものが全体のどこにあたるのかを明確にする。
- •論理的な構成
- •話の流れは論理的か（例: PREP法、背景 → 課題 → 提案 → 詳細 → 結論）。
- •⭐️論理を展開するにあたり、まず現状を整理しているか
- •各セクションの見出しは、内容を的確に表現しているか。
- •セクション間のつながりは自然か（唐突に新しい話題が出てきていないか）。
- •情報の順序と粒度
- •前提となる知識や決定事項が、後から出てきていないか。
- •読み手にとって未知の情報を、説明なしで使っていないか。
- •本質的でない詳細は、本文から切り離しているか（例: Appendixにまとめる）。
3. 内容の明確性と説得力 (主張と根拠は確かか)
ドキュメントで伝えたい内容そのものの質に関する観点。 主張に説得力があり、誤解なく伝わるかをチェックする。
- •主張と結論
- •⭐️データや複数の案を並べるだけでなく、自らの主張や提案が明確に書かれているか（レビュアーに判断を丸投げしていないか）。
- •⭐️結論は、調査結果や考察と論理的に繋がっているか。
- •⭐️期待値は何か、それに対して実績値はどうだったか、のように説明しているか。
- •期待値が無いと、結果だけ見ても解釈しづらい
- •（あれば）今後の課題や、次のアクションについても言及されているか。
- •事実と意見の分離
- •客観的な「事実（データ、事象）」と、書き手の「意見（考察、推測）」が区別して書かれているか。
- •データと分析
- •データの出所（取得方法）は説明されているか。
- •直感に反するようなデータである場合などに、レビュアーはそのデータを具体的にどのように得たかを知りたくなることがある
- •また、同一の集計をしばらく経ってから行いたくなることもあるため、その際も簡単に再集計できるようにするためにも、使用したクエリ等は分かるようにリンクなどしておく。
- •収集した情報に対する分析や比較は十分か。
- •⭐️全体のなかでそのデータはどんな割合なのか。
- •例えば、好ましくないデータがあったとしても、割合が極小ならば無視するという選択肢も考えられる
- •データの出所（取得方法）は説明されているか。
- •表現の明確さ
- •主張内容は一意に解釈できるように書かれているか（曖昧な表現はないか）。
4. 表現の一貫性と分かりやすさ (読みやすいか)
文章、図、表などの表現方法に関する観点。 認知負荷が低く直感的に理解できるかをチェックする。
- •用語と表現
- •⭐️読み手のコンテキストを意識しているか。
- •伝わらない専門用語を多用したり、伝わらないコードの細かい話をしたりしていないか
- •「ユーザー」と「利用者」など、同じ意味の言葉が複数の表現で書かれていないか（表記揺れの防止）。
- •⭐️特に新しい概念について、命名は適切であるか。定義は明確に示されているか。
- •⭐️読み手のコンテキストを意識しているか。
- •図・表・グラフ・数値
- •複雑な内容は、文章だけでなく図や表を使って分かりやすく表現されているか。
- •⭐️図/表/グラフが何を伝えたいものなのか分かるようになっているか
- •タイトル、縦軸や横軸の説明、凡例、補足説明などが付いているか
- •情報過多になっていないか
- •グラフの軸やスケールは、ミスリードを誘うものになっていないか。
- •数値には単位が記載してあるか
- •⭐️数値を並べる際は、桁数やカンマを揃える、右揃えに統一するなど、比較しやすくなる工夫がされているか。
5. セルフレビュー (基本的な品質)
ドキュメントを提出する前に、作成者自身が確認すべき最低限のチェック項目。
- •誤字脱字や、不自然な言い回しはないか。
- •表記揺れはないか。
- •自分で読み返し、論理展開に違和感がないか。
- •第三者や未来の自分が読んでも理解できそうか。
- •指摘内容を修正したことで、整合性が取れなくなっている記述が無いか。