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

●技術文書という観点，開発文書という観点

　文書診断では，次の二つの観点を定義して，文書診断を行っています．これらの観点を設けることで，開発文書の傾向や，技術者に対する教育，さらに教育効果を確認するためのデータ抽出が可能になると考えています．

• 技術文書の観点：日本語の技術文書として適切かどうかという観点から，文書内の不備を指摘します．
• 開発文書の観点：開発文書として守らなければならない項目や，求められる役割を果たしているかどうかの観点から，文書内の不備を指摘します．

　それぞれの観点では，さらに，「用字・用語」にかかわる指摘，「文法」にかかわる指摘，「文章構造・構成・展開」にかかわる指摘などを分類できるように，複数の種別を設定しています．

　前出の診断文書の例でいうと，【指摘1】～【指摘6】は，一般的な文書の書き方から指摘されるものです．これは，技術文書の観点からの指摘です．他方，【指摘7】と【指摘8】は，開発文書としてとらえたときに指摘されるものです．例えば【指摘7】では「履歴」という見出しの位置の不備を指摘しましたが，これは一般的な技術文書で規定されるものではありません（むしろ，技術文書一般では，文書の最後に記載されていることが多いだろう）．しかし開発文書という，より限定した観点では，前述したように開発上の役割を考慮することによって，指摘対象となります．

●仕様書改善で顧客満足度が向上

　診断結果の指摘項目を，観点などの属性を決めて分析することによって，開発文書の傾向や技術者の能力，さらには組織のプロセスや，組織の能力までが見えてきます．図2と図3は，ある開発現場における一連の開発文書を診断，指摘した項目を，定義した観点と種別で分類して，その傾向をグラフにしたものです．この開発現場で実施した文書診断に要した時間や指摘件数は次の通りです．

• 診断の対象とした文書：組み込みシステム部品のソフトウェア仕様書（17文書，全128ページ）
• 診断時間：全30時間
• 診断結果 指摘項目数：全768件（技術文書の観点：498，開発文書の観点：270）

図2　技術文書の観点での指摘件数の割合

図3　開発文書の観点での指摘件数の割合

　図2の技術文書の観点では，「表記ルール」に関する指摘が3割以上あり，技術文書としての体裁に問題のある個所が多く見つかりました．具体的には，ページの振り方に不備があるとか，箇条書きの一般的な書き方に反する，などの指摘です．他方，図3の開発文書の観点では，「用字・用語」に関する指摘が半数を占めています．例えば「プログラムの部品化を行う」という要求文において，「部品化」という用語の意味が定められていませんでした．そのままでは，アーキテクチャ設計を行うことも，最終的な検査を行うこともできない状況でした．

　この開発現場では，診断の結果を受けて，分かりやすい文書の作成を心がけるようになりました．特に，上記の分析結果を基に，技術文書としての基本的な表記ルールと，開発上の用語の使い方を意識するところから，取り組みを開始していただきました．この現場の組織のマネージャの方からは，「仕様書が分かりやすくなり，提出先のお客様からの問い合わせが減少した」という評価をいただいています．

●「勘と経験」からの脱皮を模索

　正直なところ筆者は，これらの診断の観点や指摘項目の種別を，まだ厳密に体系付けておらず，勘と経験に頼って，文書診断を行っています．そこで，これらの診断の指標を定義し直し，その妥当性を検討する試みや，診断結果を異なる方法で表現する方法の研究を進めています⁽¹⁾．

　さらに，文書診断は，単に赤ペンやその結果分析に留まらず，技術者の能力向上や，プロセスの改善と組織の向上を目指します．文書診断に有効性があることは，今までの実績から定性的には分かっていますが，今後，定量的な計測もしていきたいと考えています．

●チーム内でお互いに査読してみよう

　まずは，身近なチーム内でお互いに査読し合う機会を持ってみてください．技術文書としての指摘だけでなく，「この開発文書の目的や役割は何か，それを果たしているか」，「根拠が明確か」など，開発文書としての指摘を行ってみてください．本連載の第3回で紹介した作業とドキュメンテーションを連動して進めていくためのヒントも，指摘の項目として参考になると思います，皆さんの開発経験から考えつく視点を取り入れて，独自の観点で診断してみてよいと思います．そして，お互いの観点や指摘項目を持ち寄り，チームで共通化していくのも良い方法です．具体的にどのように指摘してよいのか分からない場合には，稿末のコラム「査読や指摘の書き方：筆者の場合」を参照してみてください．

　さらに，開発文書の査読と改善点の指摘をドキュメント・レビューとして，ぜひ開発の標準プロセスに組み入れることをお勧めします．設計などの公式レビューの前段階として実施するとよいでしょう．つまり，公式レビューの前に，誤記や日本語文法の誤りなどの基本的なライティング・チェックだけでなく，意味の分かりにくい表現をあらかじめ指摘します．それを開発者が修正したうえで公式レビューに臨むことによって，レビューを円滑に進められるでしょう．

　ぜひ，ドキュメンテーションと文書診断を開発作業の中に組み入れ，書く能力を上げることと開発力を上げることを，日々の仕事を通じて継続的に行ってみてください．

*　　　　　*　　　　　*

　次回は，文書診断後の治療や予防のヒントを紹介します．

参考・引用*文献
（1）藤田悠，山本雅基，中澤達夫，塩谷敦子，池田貴一，楡井雅巳，小野伸幸；文書診断図を用いたソフトウェア開発文書の診断表現，組込みシステムシンポジウム2010論文集，Vol.2010, No.10, pp.49-54, 2010

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