ドキュメントに「夜間バッチ」と書いてはいけない

わかりやすい文章を書く「見る目」を養う

　仕様書、指示書、提案書、計画書等々、IT技術者が書かなければならない書類は多種多様である。それらの文書を少しでもわかりやすく書ければ、コミュニケーション改善に効果があり、その分仕事が楽になるというものだ。

　そして、文書の種類により書くべき項目がそれぞれ違っても、大抵どの文書にも「日本語による説明文」がなんらかの形で入っている。ということは、その「日本語による説明文」の品質を向上させれば、文書全体の品質向上にも役立つということだ。

　そこでこの連載は「日本語による説明文（数行程度の短いもの）」の品質向上を目的として、IT技術者が直面するさまざまな文書事例からその問題点と改善策を検討しようというテーマを設定した。

　どんな文書にも数行程度の短い説明文は何かしら入っているし、その数行の範囲でも何かしら改善点は見つかるものだ。そんな短い文面の改善策を考えるという経験を数多く積めば、それに伴って「見る目」が養われていき、次第に良い説明文が書けるようになる。

　1日3分でいいのである。ただしできるだけ毎日1回は考えるようにしたい。では実際の事例を検討してみよう。

夜間バッチの例文

　まずは次の例文を読んでもらいたい。ある設計書の中の「夜間バッチ」に関する記述の一部である。

1.1　夜間バッチについて

　

1.1.1　目的

　毎日、全国の各支店ならびにグループ企業からの売上報告が上がってくるが、グループ企業のデータフォーマットがまちまちなため、これらを整形し直し、本社DBに格納するために夜間バッチを行う。

　

1.1.2　実行時間

夜間バッチは平日の深夜2時に動作する。なお、土日は営業がないためバッチは動作しない。

　

1.1.3　動作概要

　グループ企業内の売り上げ（本店・支店含む）は、グループ企業それぞれのDBに格納されている。夜間バッチは指定時刻に各DBにアクセスし、その日の売り上げ分を取得する。そして、そのデータを本社DBに整形して登録する。最後にバッチ動作ログテーブルにその日の売り上げを集計したことを記録する。

　基本設計書にはよくある書き方で、一見すると特に問題ないように見える。しかしこのような設計書を読む時・書く時には、「設計が適切かどうか」だけではなく、「説明文が適切かどうか」についても執念深く鵜の目鷹の目で検討するようにして欲しい。

　例文は10行以上あるが、大まかに3つのブロックに分かれているので1ブロックあたりにすれば5行以下である。5行以下の文であれば考えるのにもそれほど時間はかからないはずだ。