1 レビューをデザインしよう
1.1 レビューの工程を共有しよう
システム開発に工程があるように、レビューにも工程という考えが必要だ。システム開発では、機能の設計の前に細かいプログラムの設計は行わない。機能を洗い出し、機能の仕様を決めた後で行うのが一般的だ。
同じように、レビューも何からチェックするのか、順を追って進めるようにすべきだ。誤字・脱字や文章表現についてチェックするよりも、ドキュメントに記載すべき内容が網羅されているのか、ドキュメントの書き方が標準的か、そのようなことからチェックをすべきなのだ。
また、レビューの工程を決めたら、それを事前に関係者と共有しよう。「今日のレビューでは○○をチェックしてもらう予定です」と伝え、本筋と異なるチェックが行われないようにしよう。
1.2 観点を決めてレビューをしよう
レビューをするとレビューアが思い思いの指摘をあげる。例えば「漢字の使い方が間違っている」「フォントが揃っていない」「もっと図を取り入れたほうがよい」「昨日のレビューでは○○を利用すると決定したが、それが反映されていない」「クラスの粒度が大きすぎる」など。ドキュメントを見て頭に浮かんだものを思い思いに指摘をすることは、多様な意見をもらうことができるので作成者にとって有益な情報になることがある。
しかし、無計画にレビューするのは避けるべきだ。思い思いに頭に浮かんだものを指摘するということは、逆にいえばドキュメントを見て自動的に頭に浮かばなかった指摘が漏れるということだ。観点を定めず無計画にレビューを行えば、チェックが漏れてしまったり、レビュー完了まで何回も修正を繰り返すことになったりしてしまう。そのようなことにならないよう、レビューでは好き勝手に指摘をあげるのではなく、計画的に戦略的に観点を定めて行うべきだ。例えば「レビューの初期段階は網羅性について確認する」「網羅性が確認できたら設計の妥当性を確認する」「設計の妥当性が確認できたら表現の良し悪しを確認する」というように計画的・効率的に観点を定めるべきだ。
観点の例は以下を参考に
- 網羅性：書かれるべき項目が網羅されているか
- 正確性：書かれている内容が正確か
- わかりやすさ：読者にわかりやすく表現されているか
- 標準化：ルールに合った記載になっているか
- 文書内整合性：文書の内部で整合性がとれているか
- 他文書間整合性：他文書との間で整合性がとれているか
- 文書内表記統一：文書の内部で表記に不一致がないか
- 他文書間表記統一：他文書との間で表記に不一致がないか
- 他文書修正による影響有無：他文書に修正があった際に影響をうけることがないか
- 後工程成果物修正による影響有無：後工程で作成される文書に修正があった際に影響をうけることがないか
- 環境変更による影響有無：ディレクトリ構成、IPアドレス、筐体などが変更になった際に影響をうけることがないか
- etc
1.3 影響の大きいものを優先してレビューしよう
レビューで見逃していけないのは、“見逃すと修正に大きな工数が発生する”ものだ。設計書に書かれた漢字が誤っていた場合、仮にそれを見逃してもプログラミングやテストに影響をおよぼすことは少ない。しかし、ロジックの内容が誤っていた場合、仮にそれを見逃してしまったら、設計書の修正、プログラムの修正、テストのやりなおしが必要になってしまう。このような誤りはできるだけ早い段階で検出すべきだ。レビューでは工数に大きく影響があるものは優先的に確認するようにしよう。
1.4 指摘対応の方針を決めよう
レビューで挙がる指摘には様々なものがある。すべての指摘に対応することが望ましいが、時間の制約などによりできないことがある。そのため、事前にどのような指摘に対して優先して対応するか検討しておくようにしよう。例えば、仕様誤りであれば修正対応が必ず必要だ。しかし「である調で書くべきだが、ですます調で書かれている」など、対応しなくてもシステムの品質に影響ないものもある。そのような指摘についしては対応を劣後してもよいだろう。
優先／劣後の判断基準の例としては以下を参考に
| No | 分類 | 説明 | バグ原因 | 優先／劣後 |
|---|---|---|---|---|
| 1 | 仕様誤り | 誤った仕様が書かれている。 | Yes | 優先 |
| 2 | 仕様漏れ | 必要な仕様が書かれていない。 | Yes | 優先 |
| 3 | 意味不明 | 文章の内容が理解できず正しく意図が伝わらない。 | Yes | 優先 |
| 4 | 誤解 | 間違った意味を伝えてしまう。 | Yes | 優先 |
| 5 | 不統一（※1） | 文書によって、ページによって、作成者によって書き方が異る。 | No | 劣後 |
| 6 | 単純誤記（※2） | 文章の内容に問題はないが記載に誤りがある。 | No | 劣後 |
※1 例
A「入力情報をテーブルに登録する」
B「入力された情報をテーブルに登録する」
※2 例
×「検索結果が0件の場合はメッセージをを表示する」
○「検索結果が0件の場合はメッセージを表示する」
1.5 想定読者を決めよう
レビューをしていると、内容の良し悪しではなく、わかりやすいかわかりにくいかの議論になることがある。Aさんにはわかりづらいが、Bさんには何も問題がないということがある。その原因が、読者の経験やスキルによるものでかもしれない。読者の経験やスキルが高いことを前提にすれば、説明は少なくて済むことが多い。一方、経験やスキルが低いことを前提にすれば、説明はしっかりしなければならない。どちらを基準にするか。これを事前に決めておくと手戻りが少なくなるだろう。
2 ドキュメント作成で気をつけること
2.1 他ページや他ドキュメントの参照を正しく表記しておこう
作成しているドキュメントにすべての情報を記載せず、他ドキュメントや他ページに委ねるときは、参照先を明記しよう。可能であればファイル名や置き場所まで明記しよう。ただし、ファイル名や置き場所は、時間が経つと変わってしまう可能性があるので注意が必要だ。また、参照先のドキュメントが後工程のドキュメントの場合、その修正に引きずられないようにすることが大切だ。たとえば、基本設計のドキュメントが詳細設計のドキュメントを参照していると、詳細設計工程で基本設計工程の成果物を更新しなければならなくなる。後に戻って成果物を修正することが難しい場合もあるから要注意だ。
2.2 他ページや他ドキュメントと用語をそろえておこう
同じ概念を指す場合でも、いくつか異なる名称を持つことがある。「APサーバ」「アプリケーションサーバ」「Tomcat」など、実質的に同じ意味であっても、その時々の気分によって使う単語がことなることがよくある。そうすると、同じドキュメントであってもページによって別の用語で書かれるような場合は、誤解を与えてしまうことがある。作成者は同じものだとわかっていても、読者は別のものなのかと勘違いしてしまう。そのようなことを避けるためにも、用語をそろえるようにしよう。
2.3 誤字・脱字をつぶしておこう
レビューをするにあたって、誤字・脱字を指摘することは本質的なことではないのかもしれない。しかし、あまりにもそれが多いと読むほうは内容が頭に入ってこなくなってしまう。レビュー以前に、内容が頭に入らなければレビューは成り立たない。レビューの前には必ず誤字・脱字をチェックするようにしよう。
3 レビューの準備で気をつけること
3.1 複数の資料を印刷して配布する場合は資料に記号をつけよう
レビューの際、印刷した資料を配布することがある。配布する資料が複数ある場合は、レビュー中にどの資料を説明しているのかわからなくなることがある。レビューアが混乱しないよう、資料に記号をつけるとよい。「A」「B」や「①」「②」などでも構わないし、「画面」「DB」という短い単語でも構わない。そしてレビューでは、「Aの資料の3ページ目をご覧ください」というように今どの資料を読んでいるのかわかるようにガイドすると、レビューアが混乱しなくなる。
3.2 対面レビューでない場合は見てほしい観点を伝える
電子ファイルを渡して時間があるときに確認してもらう場合には、見てほしい観点を伝えよう。隅々まで確認するのは大変な作業になってしまう。そのようなことがないよう、見るべき箇所を限定してあげよう。「2章の修正箇所について認識が合っているか確認してほしい」というように伝えれば、すぐにレビューを終えてフィードバックができるようになる。
4 レビューで気をつけること
4.1 指摘の真意を確認しよう
指摘された際、修正方法だけを指示されることがあるだろう。例えば「『DB』は『データベース』と変えてほしい」など。指示された通りに修正を行うのではなく、その真意を確認しよう。もしかしたら「アルファベット略称を避け、カタカナ表記を推奨する」という方針が定められているとしたら、「DB」以外にもアルファベット略称で表記箇している所を修正しなければならない。真意がわかれば「DB」以外にもアルファベット略称を自分で見つけて修正することが可能だ。真意を理解しなければ、仮に「DWH」、「DBMS」、「AP」といった略称をそのまま放置してしまうだろう。指摘の真意を確認することが大切だ。
4.2 レビューイを攻撃しない
レビューで気をつけるべき点は、「レビューアが間違いを正してあげている」という意図が出てしまうことだ。一般的に、レビューではお客さん、上司、経験ある人、スキル高い人など、いわゆる「偉い人」や「できる人」がレビューアになることが多い。そのため、レビューアの場ではダメ出し、苦情、叱責など攻撃行為が行われやすい。本来であれば、ゴール（ドキュメント作成の完了）に向けてみんなが力を合わせる必要がある。しかし、攻撃の場になってしまうと、レビューイは萎縮してしまったり、嫌気がさしてしまったりして、当たり障りのない説明をして早くレビューを済ませようとしてしまう。
攻撃の場にしないためには、「作成したものを双方が協力してよりよいものに磨きをかける」という姿勢を持つことだ。野球であれば、レビューイとレビューアはピッチャーとキャッチャーの関係のようなものだ。相手に点を取られてしまったらピッチャーはがっかりするだろう。キャッチャーも残念に思うだろう。しかし、キャッチャーは「おまえのピッチングは最悪だ。こんなんじゃ勝てっこない。勝手にしろ」とは言わないだろう。レビューアも同じようにレビューイを支えてあげるべきなのだ。
4.3 レビューアがすべて指摘できるとはかぎらない
レビューではすべての指摘が行え、レビューが終われば完璧なものになるとはかぎらない。レビューアも人間であって神ではない。見過ごすこともあるだろう。「レビューを通したのだから、設計書にバグがあってもそれはレビューアの責任だ」とは考えてはいけない。もし設計書にバグがあれば、それは作成者が責任を持って修正を行うべきなのだ。
4.4 「良い出し」をしよう
レビューはダメ出しだけでなく「良い出し」もするようにしよう。作成者に肯定的なフィードバックをすることでやる気を高めることができる。また、肯定することで成果物に必要な要素を明確にすることができる。ダメ出しを取り込むだけでは断片的な補正になってしまい、全体として一貫性のある成果物にはならない。またダメ出しに対応した結果、必要な要素まで削ってしまうこともある。まずは良い点を積み重ね、成果物の骨格を仕上げよう。その上でダメ出しを取り込めば、確立された骨格に沿った良い成果物になるだろう。
5 レビュー後の対応で気をつけること
5.1 指摘箇所の修正は横展開に気をつける
レビューで指摘をうけたら、ドキュメントを修正する。このとき注意が必要なのは、直接指摘されていないページやドキュメントも横展開することを忘れないことだ。
また、ドキュメントを修正することで、整合性をあわせるために他のドキュメントを修正する必要が発生することもある。いずれにしても、指摘された箇所以外の影響も含めて修正を行おう。
5.2 指摘内容をチーム全体に共有しよう
レビューで指摘された内容は自分が作成したドキュメントだけに該当するものでないこともある。同じ修正を横展開する必要があったり、書き方の標準ルールが変更になったりすることもある。そのような周知事項は速やかに行おう。