ラベル付きステートメント構造を使え
さて、「日本語による説明文（数行程度の短いもの）」の品質向上を目的として、IT技術者が直面するさまざまな文書事例からその問題点と改善策を検討する本連載、第2回のテーマは「文章を書くな、ラベル付きステートメント構造を使え」というものである。
ラベル付きステートメント構造という用語は見慣れないことと思うが、私がつい最近作った造語であることをお断りしておこう。一部のプログラム言語に類似の用語があるがまったく関係ない。
それがどんなものかを説明する前に、まずは次の例文を読んでもらいたい。ある設計書の中の「売上集計ジョブ」に関する記述の一部である。
売上集計ジョブの例文
1.1 売上集計ジョブについて
1.1.1 目的
毎日、全国の各支店ならびにグループ企業からの売上報告が上がってくるが、グループ企業のデータフォーマットがまちまちなため、これらを整形し直し、本社DBに格納するために売上集計ジョブを行う。
1.1.2 実行時間
売上集計ジョブは平日の深夜2時に動作する。なお、土日は営業がないため動作しない。
1.1.3 動作概要
グループ企業内の売り上げ（本店・支店含む）は、グループ企業それぞれのDBに格納されている。売上集計ジョブは指定時刻に各DBにアクセスし、その日の売り上げ分を取得する。そして、そのデータを本社DBに整形して登録する。最後にバッチ動作ログテーブルにその日の売り上げを集計したことを記録する。
これは前回の出題例文の「夜間バッチ」を「売上集計ジョブ」に変えただけのテキストである。前回考察した問題点を修正したのが今回の例文ということは、他にも問題点が残っているのだろうか？
実はそうなのだ。今度は最後の「動作概要」のブロックに改善の余地がある。
普通の「文章」は仕様記述には向かない
「動作概要」のブロックに問題がある、といっても、この説明文が文章として読みにくいとか、わかりにくいということではない。強いていうなら「データを本社DBに整形して登録する」ではなく「データを整形して本社DBに登録する」の方がよいが、それは大した問題ではない。問題は実は、
「文章」を書いていること
それ自体だったりする。そもそも「文章」は仕様記述という用途には向かないのである。
「文章」でなければどう書けば良いのか、ここで改善案をご覧いただこう。
【データ構造】グループ企業内の売り上げ（本店・支店含む）は、グループ企業それぞれのDBに格納されている。
【Step1 売上取得】売上集計ジョブは指定時刻に各DBにアクセスし、その日の売り上げ分を取得する。
【Step2 整形・格納】そして、そのデータを整形して本社DBに格納する。
【Step3 ログ記録】最後にバッチ動作ログテーブルにその日の売り上げを集計したことを記録する。
このような形式を私は「ラベル付きステートメント構造」と呼んでいる。箇条書きの一種だが、【データ構造】のような各項先頭の見出し部分が「ラベル」であり、その後ろの「グループ企業内の～格納されている」という本文部分が「ステートメント」である。
ラベル付きステートメント構造で仕様説明文を記述する場合、重要なポイントとして以下のような注意点がある。
- ステートメントは「1つの意味だけを表現する」ように極力短くする
- ステートメントの記述順序に注意し、意味のある順番にはナンバーを振る（Step1、Step2などがその部分）
- ステートメントには極力「ラベル」をつけるようにする
注意点A項について補足しておこう。「ステートメント」という概念を私は「1つの意味だけを明確に表現した短い文」という意味で使っている。要するに文章術のノウハウでよく言われる「一文一意」（ワンセンテンス・ワンミーニング）を守って書いた1文のことである。
仕様説明文でこのようなラベル付きステートメント構造を使うことには大きなメリットがある。ここで、出題例文と改善案を見比べながら、どんなメリットがあるかを考えてみよう。
