理系のための文書作成術(3) ―― 開発文書の書き方はしごとのやり方を示す

この連載では，ソフトウェア開発を例に，「どんな文書が開発を妨げるのか」，「分かりやすい開発文書を書くにはどうしたらよいのか」，「文書作成をどのように開発業務に組み入れていけば，品質と生産性が上がるのか」について考察する．今回は，開発作業と文書作成を連動して進めることの意義と，やり方についての具体的なヒントを紹介する．（編集部）

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

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

「仕様書は仕様を定義した結果を書いたものである」，「設計書は設計結果を書いたものである」と，私たちは考えがちです．この考えから，文書作成を開発作業とは別の作業として位置づけている開発者は少なくありません．そして，開発の個々の作業の後に行う作業として，開発の結果や作業記録を文書に残すということを行いがちです．そもそもプロジェクト計画を立てる時点で，「プログラム納入」後に「文書整備」という作業工程を設けて，そこで一気に開発文書の作成を行うといった計画を立てる管理者も数多く存在します．これは大変危険な進め方です．

　ソフトウェアの開発では，開発文書の作成，つまりドキュメンテーションという行為を開発作業の中に織り込むことが，とても重要です．本稿では，その意義を説明し，さらに着実に進めるためのヒントを紹介します．ソフトウェア開発作業に限らず，作業の成果として文書を書くしごとにも有効なヒントになると思います

●なぜ，開発作業の後で文書を作ってはいけないのか

　開発作業を終えてから，作業の成果や記録を残すために文書を作成すると考えていると，納期や次の工程に入る時期が迫ってくることで，ドキュメンテーションの優先順位が下がります．そして，開発文書を不十分なまま，その作成を終えたり，時には作成しないままに次の工程に入ることさえあります．ついには，ドキュメンテーションの時間を確保せずに開発を進めることが常態になってしまいます．これでは，上流工程で作り込んだつもりの品質が下流の工程に伝わりません．そして伝わらないままに開発が進み，最終段階の品質が確保されないという重大な問題を引き起こすことになります．

　問題が大きければ大きいほど作業の後戻りが大きく，取り返しがつかないほどに時間がひっ迫し，開発体制の組み替えなどという大問題に発展することもあります．また，周辺の業務や後に予定している業務にも大きな犠牲を強いることになります．それらの業務に十分な時間や人的資源を確保することが難しくなり，広範囲の業務にわたってさらに重大な品質問題を生むという悪循環に陥ります．

　品質問題の原因には種々ありますが，中でも，上述のように個々の工程での品質確保が不十分なために，後の工程に進むにつれてどんどん問題が大きくなっていくような品質問題だけは避けたいものです．個々のほころびをその場で修繕できるように，ドキュメンテーションという行為を，開発作業の後ではなく，ぜひとも開発作業の中で進めたいものです．

●作業とドキュメンテーションを連動して進めよう

　ソフトウェア開発とドキュメンテーションの作業の流れを図1に示します．両者が類似していることに着目してください．

図1　ソフトウェア開発とドキュメンテーションの流れ

　ソフトウェア開発では「3．作業を実施する」，ドキュメンテーションでは「3．記述する」が中心作業として位置付けられます．中心作業に入るには，作業の目的と，実際に行う中心作業の構成という2点を明確にしなければなりません．いわば，中心作業の設計計画にあたります．この設計計画をソフトウェア開発では「1．開発すべきソフトウェアを明確にする」と「2．作業項目を決める」で，ドキュメンテーションでは「1．文書が担う記述テーマを明確にする」と「2．記述項目を決める」で行っています．

　上述の設計計画を行った上で，ソフトウェア開発では「3．作業を実施する」を，ドキュメンテーションでは「3．記述する」を中心作業として行います．中心作業が済むと，その確認と必要な改修へと作業が流れます．ソフトウェア開発でもドキュメンテーションでも，「4」と「5」がこの流れに対応します．

　このように，ソフトウェア開発とドキュメンテーションは，図1に示したように作業を対応付けることができます．そこで，この二つを連動して進めてみてはいかがでしょうか．あらかじめこの二つを連動して進めるものとしてとらえると，ソフトウェア開発だけを先に進めて，後で，それをなぞるように文書を作成することは，かえって二重に時間がかかるように思えてきます．もしかすると多くの現場では，ドキュメンテーションを後回しにすることによって，この二重の過重プロセスが実施されているのではないでしょうか．あらためて検証してみる価値はありそうです．

　「そうは言われても，なかなか作業しながら文書を書いていくことは難しい」と感じる読者もいらっしゃるでしょう．そこで，作業とドキュメンテーションを連動して進めていくためのヒントをいくつかご紹介します．