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

●目次で作業計画を示す

　図1に示したソフトウェア開発の作業の設計計画（「1．開発すべきソフトウェアを明確にする」と「2．作業項目を決める」）は，開発文書のドキュメンテーションの設計計画（「1．文書が担う記述テーマを明確にする」と「2．記述項目を決める」）そのものです．従って，開発作業の設計計画作りがそのままドキュメントの目次作りになります．開発作業とドキュメンテーションが同一の作業になっていることの好例です．そこで，開発作業の設計計画を決めるときに，まず開発文書の目次を作りましょう．

　開発文書の目次作りには具体的に次のような意味があります．

• 実施すべき作業の全体像を明示する
• 目次の構成要素で開発作業の項目を定義する
• 目次は各工程における作業計画となる

　目次を決めずに文書を書き出すと，行き当たりばったりの記述になります．書くべき事項からそれるだけでなく，そもそもの文書の目的からも外れてしまうかもしれません．最初に，文書の着地点を明確にして，その着地点に向かって，文書をいくつかの記述事項に分割していくことが文書の目次作りといえます．これは，開発作業のスタート地点で，ゴールを決めて，ゴールに向かうために作業を分割して割り当てることと同じです．

　ソフトウェア開発のプロジェクト管理でよく用いられるWBS（work breakdown structure）は，作業の構成を示すものです．目次は文書のWBSと見ることができると共に，まさに開発作業のWBSの一つの表現であるとさえ言ってもよいでしょう．

　このように，目次作りは書き手自身が記述と作業の計画を立てることにほかなりません．そして，記述の計画を，実際に行う作業の計画に合わせることが，しごとを進めるコツとなります．従って，目次は最初に作るものです．そして，この最初の作業設計計画に十分な力を傾注しなければなりません．これが開発を成功させる鍵となります．

　なお，最初に作った目次は，必ずしも絶対的なものではありません．計画は作業の進み具合や問題の発生によって，臨機応変に変更していくものです．計画と実際を常に合致させる努力と，現状を常時適正に判断してそのとき以降の計画の妥当性を確認する努力を前提として，計画変更やむなしとなれば，目次の変更も途中で行います．常に目次が適切かどうか，目次と本文の記述が合っているかを意識することは，文書と作業の全体像と，現在の自分の位置を照らし合わせてしごとをすることになります．これは，自分のしごとが，文書と作業の目的から外れずに，求められる内容を着実に実施していくことにつながります．

図2に，設計書の目次の例を示します．実際の開発文書の目次は，このように1階層だけの章立てではないと思いますが，ここでは例として，ごく簡単なものを用います．

図2　作業計画を示すソフトウェア・アーキテクチャ設計書の目次例

　この設計書の目次の章の構成は，ソフトウェアのアーキテクチャ設計の手順を意識したものになっています．まずは「1. 本書の概要」を書くことによって，この文書の目的と役割を書き手自身が確認することになります．この章は，開発作業の中で，文書がどのような位置付けにあるのか，この設計文書に何が求められているかをはっきりさせて，それを自分と開発メンバに明示するために存在します．後工程で，この文書を読むプログラマは，この章によって，設計書の目的と役割を理解します．

　次に，「2. システムの概要」の章でシステム全体を確認して，作るべきプログラムのイメージを具体化させます．そして，「3. 設計の前提と方針」で設計の方向性を宣言した上で，実際のソフトウェア・アーキテクチャの設計に入っていきます．この設計書の例では，大きなまとまりから段階的に小さなまとまりへと設計を進めています．これは，あくまでも一例です．設計手法に応じて，以下の各章は適切に改訂されるべきです．例えば，タスクの設計やクラスの設計などの章が必要になる場合もあります．

　このように，実際の作業に合わせた目次で文書を構造化することで，開発作業の流れを整理できることに注目してください．実際に作業を実施するときは，目次に従って進めていきます．もちろん，設計手法や開発プロセスによっては，各章を完全に記述する前に，次の章の記述を行うこともあります．いずれにしても，章や節ごとに作業を行い，文書として記述することが重要です．こうすることで，記述がどこまで進んでいるかを確認することが，開発作業がどこまで進んでいるかを把握することと等しくなります．

　文書に基づいて作業の進み具合を確認するので，主観や感覚に頼らずに進捗状況を把握できます．頭の中で設計を進め，「○○プログラムのアーキテクチャ設計はだいたい50％くらい進んでいます」などとあいまいな言い方でマネージャに進捗報告しなくても済みます．自ずと自分のしごとの進捗に自信が持て，安心感も得られるのではないでしょうか．

　「作業を可視化しましょう」と言われます．目次に従ってしごとを行い，文書を書くことは，まさにこの可視化を実現する方法です．これによって，しごとをほかの人に見えるようにすると共に，自分自身が自分のしごとを客観的に見ることができます．