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

●章・節の見出しが不明確

【指摘1】「1．概要」は，何の概要なのかが不明です．
この文書では，1.1.に「製品の特徴」とあるので，その上位である1章（1．）では，「特徴」ほかを総括した「製品の概要」を示したいのではないかと推測しました．しかし，1.2.がないため，1章と1.1.の階層構造の持つ意味が不明です．つまり，「概要」が「何の概要か」がはっきりしません．「1．概要」が「何の概要であるか」を明示すれば，1章全体で何を示すかが分かり，章・節の階層構造の持つ意味も明確になります．

【指摘2】「1.1. 製品の特徴」の「製品」が何を示しているか不明です．
「製品」が，文書が対象としている「水漏れ検出プログラム」とどのような関係にあるのかが不明です．目次からその関係を読み取れないとしても，どこに関係が書いてあるのかが分かるような目次の見出しをつけましょう．

【指摘3】「2．構成」は，何の構成かが不明です．
「水漏れ検出プログラム要求仕様書」という文書名から推測すると，これはプログラムの構成を指しているように考えられます．あるいは，「水漏れ検出プログラム」を組み込むシステムにおけるプログラムの位置付けを記述したかったのかもしれません．しかし下位の節の構成を見ると，ハードウェアを含むシステム全体の構成が書かれているようにも思われます．これらの疑問を解消するためには，安易に「構成」とは書かずに，「何の構成か」を具体的に示す見出しを付ける必要があります．

【指摘4】「履歴」は，何の履歴かが不明です．
稿末にある「履歴」は，文書の改訂履歴であることが推測できます．しかし，プログラムの改訂履歴や開発の経緯のように受け取られる可能性もあります．

●文書構造・目次構成が不適切

【指摘5】4.1.がなく，4.1.1.を置くのは構成として不適切です．
「4.1.」という節に当たる階層がなく，その下の4.1.1.（項に当たる階層）が入っています．4.1.1.は，4.1.の下に置くべきなので，4章の構成が不適切です．

【指摘6】1章と4章の章内に，節（や項）が一つずつしかありません．
一般的に，章に下位階層を設けることは，論旨を展開していくために有効です．しかし，1章の展開先が1.1.だけであり1.2.がないということは，どのように展開するつもりかが不明であり，特別な理由がない限り不適切な構成です．下位を単一の展開とする場合には，その理由や展開の方針を記述する必要があります．理由としては，次のような事項が考えられます．

• 上位の章・節などの記述が長くなる，または内容が抽象的すぎるなどの問題を，下位展開によって分かりやすく，また読みやすくするため．
• 今後の文書改訂において，節などを増やす可能性があるため（開発文書では，機能追加の予定など，将来を見通して目次構成を定義することもある）．

　なお，章や節などを下位階層に展開する際には，読み手に「なぜ，ここで下位に展開して記述しているのか」と不思議に思わせないように心がけましょう．すなわち，展開前の本文には，展開内容の要約や総論，導入などを記述します．また，展開に入る前に，展開の趣旨や構成説明などを記述します．

【指摘7】文書構成上，「履歴」の位置が不適切です．
この「履歴」が開発文書の改訂履歴であるなら，文書の最後ではなく冒頭に書いた方がよいです．改訂履歴は，開発文書の位置づけの意味を持ちます．ごく初期の開発文書か，または何度も改訂を重ねたものかは，開発において重要な情報である場合があります．改訂日付の情報も開発期間の位置づけを示すので，省略できません．改訂者の記載は，問い合わせ先や責任の所在を明らかにするので，開発文書にとって重要な情報の一つです．筆者は，このような重要な情報を記載する場所を，開発文書の冒頭にすべきであると考えます．冒頭に記載することで，履歴の更新漏れを防ぐことにもつながります．

●タイトルと内容が一致していない

【指摘8】目次から判断できる内容は，「要求仕様書」という文書タイトルに合致していません．
目次から推測すると，この開発文書の3章や4章では処理方法が述べられているようです．処理方法は「要求仕様」ではありません．「～を検出する」「～のデータを処理する」「～を表示する」ことが仕様です．そして，その仕様の実現の仕方が「処理方法」であるといえます．