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

●見出しと本文を一致させて作業のブレをなくす

　文書の中で，「見出し」としての役割を果たすものは，いろいろあります．まず，文書全体の見出しとして「文書名」があります．例えば「AAAプログラム要求仕様書」という文書名は，AAAプログラムの要求仕様を記述する文書であることを示す見出しです．また，文書内の章や節のタイトル，図や表のタイトル，箇条書きの見出しなども，それぞれ対応する内容が一見して分かるようにするための見出しです．

　「見出しとその内容を一致させましょう」とは，言うまでもなく，分かりやすい文書を書く際に意識するべき事項です．そして，開発文書を書く場面においても重要な意味を持ち，本稿の最初の項で述べた「作業とドキュメンテーションを連動して進める」ために，ぜひとも意識したい事柄です．目次の作成と同じように，見出しはその内容を書く前に決めます．「見出しを決める」ということは，これから「何を書くかを決める」ことと考えてください．「本文を書いた後で見出しをつける」という書き方は，特に開発文書では避けましょう．見出しで「何を書くかを決める」ことは，「作業として何をするかを決める」ことになるからです．

　例えば，図3では「ABCプログラム要求仕様書」という文書タイトルに対して，文書全体の記述内容がタイトルにきちんと合っていなければなりません．タイトルに適合する内容を記述した，ということは，「ABCプログラムの要求仕様を定義する」という計画に対して，必要十分な作業を実施した，ということになります．さらに，第1章AAAという見出しに対して，1章全体でAAAに合致する作業を実施して記述します．このように，それぞれの見出しに対して，見出しが示す本文の範囲において，内容が一致するように必要十分な作業と記述を行います．

図3　それぞれの見出しと本文の内容

　このように，「見出しで決めたこと」が，常に開発作業と記述の計画事項であり，「見出しと一致する内容を記述する」ことが，計画からぶれない実施を可能にします．

●冒頭の要旨で作業の姿勢を示す

　一般的な分かりやすい文書や文章の書き方を紹介する多くの書籍では，「結論を先に書くこと」を勧めています．多くの場合に，文章はそのように書くべきです．実際に，学術論文では，論文の冒頭にアブストラクトと呼ばれる部分があり，ここに論文の内容を簡潔に，そして包括的にまとめます．開発文書でも，記述の内容を簡潔にまとめた要旨を，アブストラクトのように本文の冒頭に入れることをお勧めします．特に開発文書では，文書の冒頭だけでなく，各章や節，段落などの文章のまとまりごとに，要旨をそれぞれの冒頭で記述することを推奨します．

　とかく，ソフトウェア開発文書は難解になりがちです．例えば，書き手にとっては自明な設計かもしれませんが，異なる設計方針を前提にしているかもしれない読み手にとっては，まず要点が示されなければ，すんなりと読むことができません．文書の冒頭や各章の最初に，そこで記述することの要旨を書くことは，読み手に対して，続く本文の内容をより理解しやすく導くことで分かりやすいものにする，という効果があります．さらに，書き手自身にとって，前項で述べた「見出しと本文を一致させる」ための助けにもなります．書き手は，これから書こうとすることを自ら把握することになり，明確な文書の記述を助けます．ですから，書き手は本文で要旨をまず記述するように習慣付けましょう．

　図4に，章の記述例を示します．この例では，第5章で開発対象プログラムの入出力の取り決めを行うことを，章タイトルで宣言しています．そして，冒頭で「入出力装置とのインタフェースを定義する」と，これから行う設計作業を宣言しています．さらに，5.1，5.2において，同様の記述の仕方をしながら，より詳しい内容に進んでいます．このように，それぞれのまとまりで冒頭に要旨を入れることは，文書を分かりやすくするだけでなく，書き手自身が開発作業を着実に意図通りに進めていくという姿勢を示すことになります．

図4　章や節の冒頭に要旨を記述した例