理系のための文書作成術(5) ―― 設計レビューでするべきこと，してはいけないこと

前回は，自分の作成した文書を他人に査読してもらうことにより，文書だけでなく，文書に反映される仕事自体の質も改善できることを説明した．今回は，技術的な仕事を確認するためのレビューに目を向け，レビューの対象物としての文書について考えてみる．（編集部）

技術解説・連載「理系のための文書作成術」 記事一覧
第1回　開発文書を分かりやすく記述する
第2回　図表を表現手段として活用する
第3回　開発文書の書き方はしごとのやり方を示す
第4回　自分の「赤ペン先生」を持とう
第5回　設計レビューでするべきこと，してはいけないこと
第6回　仕事で文書を「書かされている」あなたへのメッセージ

●お知らせ
　連載「理系のための文書作成術」が電子書籍になりました！
　ご購入は「Tech Village 書庫＆販売」のページから．

　行うべき仕事がきちんとなされているかを調べる方法の一つに「レビュー」があります．「レビュー」とは，主にものを作りあげる仕事において，成果物がその目的を果たしているか，誤りがないかを，その作成者とは別の人が調べて指摘することです．

●レビュー対象を明確にする

　仕事の出来栄えを別の人が調べるためには，仕事の結果を観察できる形にしなければなりません．開発の仕事に限らず，多くの技術的な仕事では，その成果を文書で示します．その文書を調べることによって，仕事が適切になされているかを，仕事を行った人とは別の人が客観的に調べます．システムやソフトウェアの開発作業では，どんなものをどのように作るかを決めますが，その仕事の結果を明確にするために，開発作業の途中で，仕様書や設計書を作成します．ですから，適切に仕様が定義されているか，設計が妥当に行われているかは，出来上がる仕様書や設計書をレビューすれば分かります．このとき，レビューの対象物は文書です．

　レビューは，仕事をした人や文書を作成した人とは別の人が行うことが原則です．レビューにおいて，文書を作成した人は別の人に文書を引き渡し，別の人はそれを受け取って文書に対する作業（レビュー）を実施します．レビューは仕事の区切りで行います．ある作業が終わり，次の作業へと仕事が進む前に，ある作業のレビューを行います（図1）．このとき，ある作業から次の作業に引き渡すものがレビュー対象物であり，作業間の移行をつなぐインターフェースとなります．

図1　仕事の区切りでレビューを実施する

　作業を開始する前には，レビューの対象となる文書がどれであるかを，明確に定義しておくとよいでしょう．この定義は「レビューを行う工程で出力される文書全般」などというあいまいなものではなく，「○○設計書Version 1.2」などと，特定できる文書名を示しましょう．レビュー対象を明確にすることが作業の質を向上させます．

●設計者をレビューしていませんか？

　開発の場では，しばしば会議形式でレビューが行われます．設計書などの文書がレビュー対象となりますから，レビュー会議では，まずは，文書の内容に対する指摘が出されることでしょう．ところが，会議が進むうちに，文書に書かれていない技術的な質問が出されることがあります．それは，しばしば，設計などの技術的な作業そのものの意味や根拠を確認するためになされます．そして，設計文書の作成者である設計者は，その質問に答えます．質問したレビューア（レビューの場で指摘する側の人）は，設計者の回答を理解し，その場で納得します．そして，会議は進んでいきます．...どこかおかしな点に気づきませんか？

　まず，レビューアは作業の意味や根拠を確認する前に，それが文書に書かれていないことを指摘しなければなりません．レビューは，仕事の内容を調べるためのものです．設計の内容を調べることが重要であって，設計書での表記の有無や，その表現を指摘することがレビューではない，と主張する人がいるかもしれません．しかしそもそも，その設計の内容が明確に書かれていないことに問題があります．設計という作業は，まさに設計の根拠を明らかにし，種々検討した成果を明確に設計書として作成することです．そして，その設計書こそがレビューの対象であり，その場で口頭で説明されることは，レビューの対象には成り得ないのです．設計書をレビューしていたつもりが，いつのまにか設計者の頭の中をレビューしていた，という場面を，筆者はしばしば目にしています．頭の中をレビューしても，それはその場の確認にすぎず，仕事の成果としては残りません．つまり，仕事がきちんとなされたかどうかを調べることには成り得ません．

●「レビューのために文書を準備しました」○か×か？

　開発作業などで，文書に対するレビューが定着してくると，文書をレビューのために作成しようと考える人が出てきます．これまでは文書作成を重視してこなかったが，レビューを行うようになったので，「文書をしっかり書くようになった」，または「読み手を意識して書くようになった」と，しばしば耳にします．レビューがドキュメンテーションの一つのきっかけになるのなら，それは大変良い傾向だと思います．しかし，ドキュメンテーションの目的はレビューではありません．

　レビューの実施に間に合わせるために文書を慌てて作ったり，レビューのために文書の体裁を整えたりすることは，好ましくないどころか，やってはいけないことと考えます．また，レビューのために，レビュー対象の文書を補足するようなプレゼン資料を，わざわざ作ることもお勧めしません．

　本連載の第3回で「開発文書の書き方はしごとのやり方を示す」ことを紹介しました．文書には仕事の内容を記述します．その際に，仕事の進み具合に従って，文書を書いていくという考え方をお勧めしました．もしレビューのために文書を準備してしまうと，仕事の進み具合や作業の品質を隠してしまうかもしれません．

　たとえ，レビュー時点で文書が完成していないとしても，むしろレビューを「仕事の未完成度合いを確認するもの」ととらえましょう．そして，仕事とドキュメンテーションを連動させることによって，文書を見れば，そのまま仕事の進捗度や出来栄えが分かるような仕事の進め方をしましょう．文書をレビューするということは，仕事の成果をレビューするだけでなく，仕事のプロセスをもレビューすることを意味しているのですから．