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

塩谷 敦子

●レビューから対処までを管理しよう

 レビューさえしていれば,成果物の品質が上がると思われている方が多くいらっしゃいます.レビューに費やした時間を計測している開発現場にも,しばしば出会います.しかし本来,レビューの場では,問題点を指摘するだけで,その解決までは行いません.指摘だけでは改善されないことを,職場の改善委員会で経験されている人も多いのではないでしょうか.どんなに多くの指摘項目が挙がってきても,それを直さない限り,なにも改善されないことは当然です.レビューの時間を計測することは否定しません.時間はレビューのやり方を改善したり,開発時間との調整,見積もりなどに有効なデータとなるでしょう.しかし,レビュー時間だけを使って,成果物の品質を測ることは危険です.

 それでは,どのようにレビューを改善につなげ,成果物の品質向上につなげるのでしょうか.まず,レビューの結果を文書化しましょう.レビュー報告書といった文書を残している開発チームは多いとは思います.しかし,その報告書が,単にレビューの議事録で終わっているということはありませんか.

 多くの開発現場では,ソフトウェアのコーディングからテストの工程で,「バグ管理表」を書いて運用していることでしょう.「バグ管理表」も一つのレビュー報告書です.「バグ管理表」では,見つかったバグに対してどのように対応するかを管理します.同じように,開発文書の指摘事項も管理できるような文書,つまりレビューで挙がった指摘が収束するまで継続して使えるレビュー報告書を作ることをお勧めします.「指摘が収束する」とは,必ずしも「すべて修正する」ことではありません.指摘事項に対して「修正しない」という対応でも構いません.しかし,「修正しない」という結論だけを書くのではなく,「なぜ修正しないのか」といった理由をぜひ書いて残してください.これは,バグ管理表でも然りです.また,「修正する」とした場合も,「誰がいつまでに行うか」「完了か未完了か」の状況が分かるように書くことも必要です.

 図2に,あるソフトウェア開発の要件定義工程での開発文書に対してドキュメント・レビューを行った際のレビュー報告書の例を示します.ドキュメント・レビューでは,レビューの対象を文書に限定して,その文書を読み込み,問題点を検出します.図2の指摘結果の欄(図内の水色見出しの部分)では,第4回で登場した,日本語の文法に関することも指摘項目として載せています.日本語の係り受け不備や,一文一義でない,といった一般的な技術文書としての問題は,技術的な検討の不十分さを示します.さらに,技術文書の基本原則において不備があると,読み手は開発の技術的な水準にも不信感を抱きかねません.

図2 ソフトウェア開発のレビュー報告書例

 対処結果の欄(図内のオレンジ色見出しの部分)では,各指摘項目に対する対処状況と,「対処不可」や「保留」に対する理由などが分かるようにしています.予定と完了欄による進捗の把握,責任の所在である対処者の記載もつけます.

●診断結果を治療と予防につなげる

 筆者らは,開発作業などの技術的な仕事を頭の中だけで行わずに,文書として表現する進め方を推進しています.そして,仕事の進捗度や出来栄えを調べるための「文書診断」を提案しています.文書診断では,レビューで行う問題点の指摘だけでなく,それらの解決と,問題点が起こらないような仕事の進め方の提案や,技術者の育成までを対象範囲とします.

 筆者らは,文書に対する「診断」の概念を説明する時に医療の場で使われる「診断」や「治療」などの用語を用いています(図3).文書診断は,「文書」や「仕事」を対象とします.しかし,そのような「もの」に対する修正や改訂だけでなく,文書の作成者である「人」と,その「人」が属する「組織」の健全化を目指すという意味をも持たせたいと思っています.図3では,従来のレビューを発展させて,赤ペン先生が行う査読による文書の診断から診断結果を出すことを,「狭義の文書診断」と定義します.そして,その診断結果から文書の改善を行うことが「治療」です.この「診断」から「治療」を繰り返し,「文書を作成すること」と「文書を診断すること」を定着させて,文書に基づいて仕事を進めていける環境を整えていくことを「予防」としています.

図3 文書診断が目指すもの

●「治そう」という気持ちが重要

 病気を治療するには,患者自身が「治そう」と思う気持ちを強く持つことが重要である,とよく言われます.これは,文書診断にもあてはまります.赤ペン先生によって査読を受けた文書がどんなに真っ赤になったとしても,診断にどれだけの指摘項目が挙がったとしても,またレビューにどれほどの時間を割いたとしても,それは「診断」に過ぎず,「治療」ではありません.もし,文書作成者が,指摘されたことに対して,「書く側の意図を読み取らないのは,読み手の問題だ」などと考え,指摘されたことを修正しないとしたら,文書は改善されません.診断もレビューも無意味なものになります.

 常に「読み損ないは書き手の粗相」ととらえて,文書を書く能力を高めることを,筆者は勧めています.読み損ないをされる開発文書は,技術的な内容がきちんと整理されていないために,技術的な水準も低く,明晰な文書として表現されていないといえます.文書の理解度合いが読み手に依存することを避け,誰が読んでも一意に解釈できる表現を心がけましょう.それが,開発の技術力を伸ばす着実な方法となります.そして万が一,書き手の意図とは異なる意味に解釈されたときには,書き手に責任があり,書き方を修正するべきだ,と考えるようにしましょう.

 診断する側とされる側は,決して対立関係にあるわけではありません.両者は文書を改善して共に成長するという,同じ方向を向いているはずです.まずは,書き手が読み手の立場で,文書を書いて診断を受ける,そして修正するという姿勢が,同じ方向の先にある「文書」と「仕事」の治療につながります.

●自分が書いた文章を読み返そう

 筆者は,ドキュメンテーション研修の講師や実際の開発文書の文書診断をする機会を多く得ています.研修中に,受講者のドキュメント作成実習の様子を見るにつけ,また受講者の方から普段のドキュメンテーション作業の仕方を聞くにつけ,自分が書いた文章を読み返さない人が多いことに驚きます.受け取ったメール文でも,「書いた後で読み返したら,このような書き方はしないはず」と感じるものも多くあります.皆さん,忙しくて読みなおす時間がとれないのでしょうか.開発文書などは,「とにかく書くだけ書いて,存在すれば事足りる,誰も読む人などいない」という状況の下で,誰にも読まれずファイリングされる場合が多いからでしょうか.

 気軽にやり取りするメールは,直接話すことの代用になってきているため,いちいち読み返さずに言葉を発するがごとく書き放つ人が多くなってきています.その感覚を,仕事の内容のメールにも,さらには報告書などの業務文書にも,持ち込む人が増えてきている気がしています.

 筆者は,常に自分が書いた文章を読み返すことを心がけています.重要な文書では,声に出して読み返すこともします.読み返すときには,自分ではない,第三者の読み手の立場で読み返すとよい,と言われます.声に出すことで,声が外からの情報となって,客観的な読み手の意識に近づけるのではないでしょうか.

 さらに,どんなに気軽な遊びのメールでも,人に読ませる以上は,最小限自分が書いたものを読み返すことが基本的なマナーであると考えます.いくらメールが話すことの代用になってきたとしても,「書いたことが形に残る」ということは,話したこととの大きな違いです.書いたものは可視化されて残ります.これは,話すことにはない最大の利点であり,その影響力は,場所と時間を超えます.

 ならば,自分の仕事は,脳内作業にせず,目に見える形として残しましょう.自分の考えを整理し,確認し,評価するために,ぜひ自分の仕事を反映させた文書を読み返しましょう.文書を分かりやすく書くこと,客観的に読み返すことは,書き手本人の分析能力,設計能力,それらを論理的に展開する能力を養うことになってきます.そして,常に,繰り返し意識することが,自己治療となり予防となります.

***

 次回は最終回の予定です.ドキュメンテーションと文書診断を総括し,少しドキュメンテーションに意識が向いてきた理系の方,まだまだ「書かされ感」から抜けられない技術者の方,そんな読者の方々を最後に元気づけられたら,と思っています.

しおや・あつこ
イオタクラフト

 

«  1  2
組み込みキャッチアップ

お知らせ 一覧を見る

電子書籍の最新刊! FPGAマガジン No.12『ARMコアFPGA×Linux初体験』好評発売中

FPGAマガジン No.11『性能UP! アルゴリズム×手仕上げHDL』好評発売中! PDF版もあります

PICK UP用語

EV(電気自動車)

関連記事

EnOcean

関連記事

Android

関連記事

ニュース 一覧を見る
Tech Villageブログ

渡辺のぼるのロボコン・プロモータ日記

2年ぶりのブログ更新w

2016年10月 9日

Hamana Project

Hamana-8最終打ち上げ報告(その2)

2012年6月26日