ドキュメントレビューをする際の10のポイント

みなさんこんにちは。@ryuzeeです。

重厚長大なドキュメントは、動かなかったり嘘が書いてあったり現実と異なっていたり、その上肝心なこと書いてなかったりということで辛いことが多いのが現状です。今回とある筋からドキュメントをレビューする際のポイントを教えて欲しい、という依頼を受けたので書いてみます。

なお、個人的には、ドキュメントレビューよりソースレビューの方が重要だと思っています。

とはいえドキュメントレビューで肝心なのは、

ドキュメントレビューをするなら、その投資に見合う何を得るのか？を決めておく必要がある
本当にそのドキュメントは必要か？をよく考える（会社のルールだから！というのは理由にはなっていない）

だと思います。

レビューのポイント

1. 体裁をレビューするのではなく、中身をレビューする

ひどい現場だと、文書のインデントやフォントのサイズ、誤字脱字ばかりを重箱の隅をつつくようにチェックしているケースがあるようです。しかし、そうではなく中身をレビューする必要があります（ただしあまりに体裁がひどい場合は、往々にして中身もひどい場合も多いようですが・・・）。中身が分からないから体裁をレビューする、というのもあるようですが、そのレビューの結果は、どんな利益を生んでいるのかよく考えるべきです。なお、レビューワーはレビュー前に資料を確認しておくべきであることは言うまでもありません。いきなり初見の資料を見てレビューできる項目はたかがしれています。

2. 標準化ではなく、顧客や案件ごとに最適化できるような自由度をチームに与える

必要なドキュメントは顧客毎、システム毎に異なります。

常に自社の標準に無理やり押し込めようとするのではなく、案件特性や顧客特性を踏また上で、どのようなドキュメントが必要なのかは最初に考えてください。そしてドキュメントも常時リファクタリングできるようにしていきましょう。

3. レビューの目的を明確にする

レビューは実施することに意義があるのではなく、そこで問題となりそうなことを早期に検出し、将来のリスクを軽減することに意味があります。レビューワーの時間、参加者の時間を投資するので、その投資に見合うリターンを生むようにしなければいけません。

4. 大がかりなレビューを少ない回数実施するのではなく、こまめな小規模レビューを繰り返す

アジャイルなレビューです。大量に作ってしまった問題あるドキュメントを修正するのは簡単なことではありません。リスクを早期に検出しクリアにするためには早期レビューと繰り返しが必須です。次の工程に入る前にとってつけたようなレビューをして、条件付きで承認をする、といったやり方をするチームもありますが非効率で、問題の先送りである。

5. レビューでの指摘事項をすべて対応しなければならないとは限らない。チームにとって労力をかけるだけのメリットがあるものから優先順位付けをして実施する

レビューワーは気づいた点を大小問わずすべて指摘するかもしれませんが、それを全て修正する必要が必ずしもあるとは限りません。修正にかけるコストと効果を勘案し、優先順位をつけて対応すれば良いでしょう。

6. レビューで人格を非難しない

ついついレビューワーは上から目線で、「こんなこともできないのか！」みたいなトーンで指摘してしまいがちです。そういうことをしていると、レビューを受ける側は、レビューを通りさえすれば何でもいいや、と思うか、レビューを受けることすら嫌がるようになります。レビューをする側も、顧客へ届ける製品の品質の一旦を担っていると考えられるので、同じ土俵の上で純粋に同じゴールに向かってレビューしてください。

7. レビューの順番もレビュー効果が高いものから実施すること

同じフェーズの設計書でも、システム内での機能の重要度には差があるはずです。全部が重要な機能である、というシステムはいまだかつて見たことがありません。限られた時間の中で最大の効果を出すためには、アジャイルで構築するフィーチャーに優先順位をつけるのと同様に、レビューする範囲にも優先順位をつけてください。レビューでは100%のレビューカバレージを取ることが目的なのではなく、問題を早期に検出し、将来にリスクを顕在化させないようにするためのものなのです。