レビュアーの心構え。コード以外のレビューの質と効率に関する6つの Tips
こんにちわ。従業員体験( EX ) の向上がミッションのエンジニアリング統括室に所属しているてぃーびーです。
私はもともとウェブエンジニア出身で、今は組織開発の仕事をしています。ソフトウェア開発者時代はレビューといえばコードレビューでした。前職で人事になってから「コード以外のレビュー」をする側・される側を経験する機会が増えました。コードレビューはツール類が発展していることもあり、円滑に進めやすい土台が整っている事が多いと思います。一方、その他の領域に関してはツール類に頼らず自らレビューのノウハウを用いて認識齟齬を避けたり、効率を上げたり、レビュー指摘〜反映の流れに抜け漏れがでないようにする必要があります。そこでレビューに際して気にしていることをまとめてみることにしました。開発者の方も、ドキュメントなどコード以外のレビューをすることがあると思いますので、参考になると嬉しいです。
コード以外のレビューとは？
コード以外のレビュー対象は以下のようなものを想定しています
- ドキュメント
- ブログ記事
- 業務プロセス
- 登壇資料
- 図
Tips
1. 見出し
指摘内容を端的に表す見出しをつけるとよいでしょう。
・求人票の件名の誤字 誤「インサイトセールス」 正「インサイドセールス」
見出しのない指摘は、指摘文の大半を読まないと指摘内容を理解できませんが、見出しがあると大枠何の話を最初に理解できます。
2. 複数の指摘を区別
複数の指摘を行う場合は、別の指摘であることがわかりやすくするとよいでしょう。タスク管理しているなら個別の課題として起票することになります。
・指摘1 指摘1の内容
・指摘2 指摘2の内容
複数の指摘が混ざっていると、内容の混同をしやすかったり、そもそもいくつの指摘をされているかわかりにくくなります。 受け手が理解する労力を可能な限り減らしましょう。
3. 指摘の頻出カテゴリを添える
見出しにカテゴリを添えることで、指摘内容の分類をすぐに把握できます。例えば、よくあるのがタイポです。 指摘をタスク管理ツールで管理する場合は、ラベル機能で属性を付ける形になるでしょう。
・【タイポ】求人票の件名の誤字 誤「確立」 正「確率」
4. できるだけ具体的な場所を知らせる
例えば100ページある文書の何ページどの部分に関する指摘なのか、受け手が一瞬で把握できる情報を提供するのが好ましいでしょう。
ドキュメントツール自体にコメント機能があれば、該当箇所へのコメントがわかりやすいでしょう。 なければページ数、行数など具体的な場所を指摘することや、指摘対象の引用で対象を明確にするとよいでしょう。指摘箇所に Permalink が存在するなら、それを添えておくとよいでしょう。 場合によっては、 Text Flagment も便利です。
ページ数、行数のパターン
・【タイポ】求人票の件名の誤字 P12, 10行目 誤「確立」 正「確率」
URL のパターン
・【タイポ】求人票の件名の誤字 https://example.com/ 誤「確立」 正「確率」
あなたが100ページ目の10行目で問題を発見して指摘をしようとするとき、受け手はその位置を知りません。あなたが伝えなければ、指摘内容をヒントに100ページ中のどこに問題かあるか探し回ることになります。
5. 参考情報の提示
相手に対して「自分は知っているが相手が知らない知識」を伝える場合、その参考文献があるならリンクを提供しましょう。 また、提供するページの一部だけを知らせたい場合は、読んでもらいたい範囲を明示しましょう。
わかりやすい Example については、 SSCCE を踏まえるとよいです。 SSCCE については、以下を確認してください。
http://sscce.org/
6. レビュー指摘と修正のサイクルをタスク管理する
レビューの指摘やそれに対する修正確認はタスクです。タスクにはタスク管理が必要です。
プログラムやシステム開発の個別の課題は課題管理ツールを用いるが、ちょっとした資料のレビューなどは課題管理しないことはよくあるのではないかと思います。結果、レビュー指摘に対する対応がもれたり、対応後の最終チェックが漏れることがありがちかと思います。
まとめ
レビューの指摘を受ける相手にとって
- 指摘内容を齟齬なく理解しやすい
- 指摘内容を理解し、実際に修正を適用するまでの時間的な手間が少ない
ほど嬉しいレビューとなるはずです。 レビュアーの指摘の仕方次第で、レビュー全体の質・効率に大きな影響があります。
個別の Tips の根本にあるのは「レビュイーのため」という心構えでのレビュー指摘をすることです。 「レビュイーのため」という心構えを持ち、レビューの質と効率を最大化できるレビュアーになりましょう。
