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

●設計の結果だけでなく根拠も記述する

　開発文書を，仕様を定義した結果や設計した結果を書くものだと考えている人が少なくありません．このために，実際に行った仕様定義や設計の作業と，ドキュメンテーションの作業とが分離してしまう，という話を既にしました．そして，実際の開発作業とドキュメンテーションとを連動して進めること，双方の作業の流れを合わせることを，本稿で解説し，そのスタイルをとることをお勧めしてきました．

　しかし，たとえ作業と連動してドキュメンテーションを行ったとしても，開発文書には作業の結果を書くものだと考えている間は，「開発作業をやった後で，それをまとめる」というやり方から脱することができないかもしれません．

　開発作業を行うとき，開発者である皆さんは，非常に多くのことを検討しているはずです．一つの設計を選択するために，さまざまな検討を繰り返し，設計根拠を考えたはずです．開発文書には，開発作業として為したことを記述していく，つまり作業結果とともに，その結果の根拠も記述していただきたいと考えます．新たに定義したこと，設計したことには，必ずその目的や理由など，結果を導くための根拠があるはずです．開発作業として為したことの根拠を，ぜひ記述してください．なぜこのようなプログラム構成としたのか，なぜこういったタスクを定義したのかを，書き残してください，

　定義や設計の根拠が，今書いている文書とは別の文書や別の作業工程にあるのかもしれません．では，どこからその情報を得たのでしょうか？ それは，元々の開発の要求から導かれている事柄の場合もあるでしょう．それを明らかにすることも，開発文書の大きな役割です．ある情報を記述するときに，その根拠がどこにあるかを明確にすることが，開発文書にとって非常に重要なのです．既に決まっていることと，新たにこの工程で取り決めることや設計することとの区別をつけることになります．作業の結果だけでなく，その根拠を記述することが，既に存在する情報を使うことか，新たに決定したことかを明示することになるのです．このことは，開発する対象を明確に理解して伝えることといえます．

***

　本稿では，開発文書を，開発作業の後で作成するのではなく，開発作業に組み込んで連動させていくために，いくつかのヒントを紹介しました．開発文書を書く中で，目次を決め，見出しと本文を一致させ，本文のまとまりごとに要旨を示して，結果だけでなく根拠を書くようにすることが，それぞれ開発作業としての意味を持ちます．これらのヒントを意識的に行っていくと，ドキュメンテーションが開発作業のやり方を示していることに気付かれることでしょう．そして，開発作業をドキュメンテーションに連動させることは，実は，「開発作業とは開発文書を作ること」であるという気がしてきませんか．

　次回は，開発作業の品質向上のために文書を改善するいくつかの事例を紹介します．

参考文献
（1）合同会社イオタクラフト；"組込みソフトウェア技術者研修 「ソフトウェアドキュメンテーション」テキスト"，合同会社イオタクラフト発行，2008年．

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