レビューしてもらう/する場合に意識すること、やり方を考える

先日ドキュメントのレビューについて相談を受けました。
『レビューをしてもらう必要性はわかっているものの、いろいろツラい』とのこと。具体的に話を聞いてみると、以下のようなツラみがあるようです。

レビューをしてもらう時のツラみ
「恥ずかしい間違いをしてしまった、不勉強がバレて恥ずかしい」
「この指摘は別にどっちでも良いのでは、、でもせっかくレビューしてもらったので言い出しにくい」
「その指摘わかるけど、ここで書くと違うから書いていないんだよな。ちゃんと背景を理解してレビューしてほしい」

レビューする時のツラみ
「なんか言い方がキツくなってしまった、嫌われないかしら」
「修正ポイントがたくさんあって、どこから指摘したら良いかわからない」
「突然レビューしてくれと言われても、どの観点から指摘すれば良いかわからない」

「わかるな〜」と思いつつ、「私はどうやってレビュー対応していたっけな？」というのを考えてみたいと思います。

レビューについて

そもそもの話として、良いドキュメントを書くにはレビューが必要です。
他者に見てもらうことによって、足りない部分を補えたり、無駄な部分を省けてスッキリさせたりできます。

メリットとしてあげるとキリがないですが、下記のような点でしょうか。

• 誤字脱字が発見できる

• 理解できない箇所が発見できる

• わかりにくい表現が発見できる

• 別の視点の意見がもらえる

• より良いドキュメントになる！

ということで、レビューでドキュメントがよくなることは間違いないです。なるべくツラみをなくすためにはどうするべきか、考えてみました。

事前準備

レビューする/してもらうためには準備が大切です。大きくは下記2つです。

• レビューをしてもらう人/する人との関係を作っておく

• ガイドラインを準備する

それぞれ説明します。

レビューをしてもらう人/する人との関係を作っておく

ほとんど話も仕事も一緒にしたことがない方に、突然レビューをお願いしても、相手としては「なぜ私に依頼したのか」「どういった観点のレビューが欲しいのか」など戸惑ってしまいます。
レビューをお願いしたい場合は、事前に下記の情報を伝えておくことが大事です。

• 今やっていていること

• 困っていること

• レビューの観点

• なぜあなたにお願いしたのか

ガイドラインを準備する

ドキュメント作成のための手助けとなるガイドブックを準備します。ガイドブックには、主にドキュメント作成において適切なフォーマットやスタイル、書き方などを指導するための方針やルールが記載されます。

ドキュメントはどのように書かれている必要があるのか、を確認するためにj必要になるので、こちらを準備して渡しておきましょう。

（ガイドラインについては下記にてnote書きましたので、併せてどうぞ）

それでは、「レビューしてもらう場合」「レビューする場合」のポイントをそれぞれ記載します。

レビューしてもらう場合

まずはレビューしてもらう場合のポイントを記載します。

意識すること

• 初めから完璧なドキュメントなどないと考える（というか、そもそも完璧なドキュメントなどない）

• レビューのおかげでドキュメントがさらに良くなると捉える

• 責められているわけではない

• 指摘は全て直すくらいの気持ちでいる

• 書いてあること以外のことは意識しない

レビューを依頼された側からすると、「せっかく依頼されたのだから、どんなに些細なことでも確認しよう！」という気持ちになります（依頼された側からすると、頼られているという責任感と、嬉しいという気持ちもあるので）。

また、書いてあること以外のことは意識しないのがポイントです。例えば下記のようなことは思わなくて良いです。

普段は語尾に「！」や絵文字を多用する方なのに、今回は「。」で終わってしまっている、きっとレビューが大変だったから怒っているんだ！

怒っていないので、書いている内容だけ気にしましょう。

やること

レビューしてもらう場合には、ドキュメントに下記を添えると見てもらいやすくなります。

■悩んだ点は素直に伝える

ドキュメントを書いていて迷うことは多々あります。その場合は素直に「悩んでいるのでどうしたら良いか一緒に考えて欲しい」と素直に伝えることが大事です。

■あえて書いていない部分があれば、コメントで補足する

理由があり削除した場合、なぜ削除したかを書くとより良いです。レビューの際に指摘が入る可能性があるので。

■締切を提示する
ビューする作業はどうしても後回しになりがちなので、締め切りをはっきりと示すことが大事です。

レビューする場合

次にレビューする場合のポイントを記載します。

意識すること

• レビュイーの背景を理解する

• 思ったことは遠慮なく伝える

• そもそも書いてくれてありがとうという気持ちを持つ

相手の背景や、なぜこのドキュメントが必要なのか、などを考えて、そのためにどういう指摘が必要かをしていくのが良いです。

やること

■ガイドラインやissueを読み込む
事前にガイドラインやissueを読みこみ、どの観点でレビューするべきかを確認します。背景や意図を確認することで、レビューの質がぐんと上がります。

■レビューを、[Must][IMO][Nit]などのカテゴリに分けて伝える
コメントが多くなってしまった場合、修正が必須なのか、軽い指摘なのかをカテゴリ分けることで、レビュイーが確認しやすくなります。

• MUST: 必ず修正した方が良い

• IMO：私の意見。必ず修正するべきだとは思わないが気になった点

• Nits：誤字脱字など、簡単な修正。細かい点。

■具体的な修正方法を提案する
「わかりにくいので修正してください」「この書き方は変です」だけの指摘だと、ではどう直すべきなのかが伝わりません。
「説明が足りていないので、XXXについての説明を追加してください」など、具体的な修正案を伝えてください。

一方で、「どう修正したら良いかの良い案が浮かばないけど気になる」という点もあるかと思います。その場合は素直にそう伝え、一緒に考えるようにすると良いです。

■良い文章には「良い！」と伝える
良い文章は良いと伝えます。レビューは指摘することばかり意識してしまいますが、この書き方良いな、素晴らしいなと思ったら積極的に伝えることが良いです。
やはり褒められると嬉しいです。

まとめ

レビューをしてもらう/する場合のポイントをまとめてみました。意識や行動を少し変えるだけでもレビューがよくなるのかなと思います。何かの参考になれば嬉しいです。

この方法が完璧ではなく、私も日々悩みながらレビューしているので、おすすめのやり方があれば教えてください。