理系のための文書作成術(4) ―― 自分の「赤ペン先生」を持とう

●俯瞰には目次の確認が重要

　ここでは，本文まで確認していませんが，まず目次から全体を俯瞰し，文書の構造を理解して，何が記述されているのかを判断することが重要です．これによって，木を見て森を見ないという誤りを防止できます．ここでは，目次から，要求仕様書に「処理方法」の記述が書かれていることの不自然さに気が付きました．要求定義の工程において行われた作業が，本来求められるものであるか否かが，目次だけで分かります．

　ご紹介してきた開発文書の例は，わずか5章分の目次です．決して長いとは言えない文書でも，目次の査読だけで，八つの指摘項目が見つかりました．いずれも，この文書で何を伝えようとしているのか，そして，その記述が合理的に展開されているのか，といった基本的な事項です．こうした指摘事項に応じて元の文書を改修する中で，開発そのものの進め方や組み立て方に根本的な問題があったことに気付く場合もあります．

　なお，実際に査読してもらう際には，目次の査読だけで終わらず，本文についても査読してもらったほうがよいのは言うまでもありません．

●開発文書を見れば品質が分かる

　本連載の第3回では，「開発作業をドキュメンテーションに連動させること」を提案しました．これは，「開発作業を映し込んで開発文書とする」というものでした．開発作業と連動して開発文書を作成すれば，開発文書の確認が開発作業の内容の確認を導くことになります．

　作業の進み具合だけでなく，作業の妥当性や品質さえも，開発文書を見れば分かります．もし開発作業に詰めの甘いところがあれば，開発文書を査読することにより，直ちに発見できます．開発文書を丁寧に読むと，あいまいな記述や論理的に不整合な記述，書くべきことが書かれていない記述などを指摘できます．つまり，開発作業をドキュメンテーションに連動させることによって，開発文書に対する指摘が，そのまま開発作業そのものへの指摘につながってくるのです．

●門外漢が開発作業の本質に赤を入れられる理由

　筆者らは，開発文書を査読することによって，文書の不備，つまりは開発作業の不備を検出し，作業を改善すると共に，作業を行った技術者を育成する活動を行っています．この活動を，医者が身体の不具合を見つけて病名を判定し，それを治療していく行為にならって，開発文書の「文書診断」と呼んでいます．「文書診断」などとえらそうな名前をつけていますが，まずは開発文書内の不適切な表記や表現などを指摘・添削する「赤ペン先生」の仕事から始めます．

　実際の開発現場で開発文書の赤ペン入れを行っていると，次のような場面に出会うことがあります．「この部分があいまいで，理解できません」という指摘に対して，書き手が「ここは○○の設計の内容を書いたつもりでした．しかし，自分でも設計の根拠があいまいで，設計結果の検討そのものが不十分だったと気づきました」と言うのです．開発現場が対象としている専門的な技術分野を筆者も専門としている場合は少なく，たいていの場合は門外漢として赤ペン先生になります．それにもかかわらず，日本語表現としての分かりにくさをストレートに指摘したことが，開発上の不備や不足の指摘につながることがあるのです．

　つまり，読み手に分かりやすく伝えようとして「書く」と，書き手は開発作業を十分に理解する必要があることに気づきます．そして，書き手が，読み手にとって分かりやすい開発文書を書くように心がけることで，自分が行うべき開発作業が何であるかを理解し，整理し，着実に行うことができるようになります．

　このように，文書の査読から，開発文書の改善だけでなく，開発作業の改善につながることは，ドキュメンテーションがもたらす意義といえます．そして，開発文書を改善していくこと，作業を反映した文書を書いていくことが，開発者の設計力などの開発能力を上げることにもつながります．筆者らは「文書診断」として，赤ペンなどで指摘した項目を分類して文書の傾向を分析し，その結果を文書作成能力や開発作業能力に対する教育支援につなげています．