Shoeisha Technology Media

EnterpriseZine(エンタープライズジン)

EnterpriseZine(エンタープライズジン)

テーマ別に探す

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

2007/07/30 11:00

 あなたの書いた仕様書の説明はわかりやすいだろうか? 一見すると何の問題もないように思える説明文でも、突き詰めて見ていくと曖昧な表現が紛れ込んでおり、正しく情報を伝えられないことがある。ここでは例題文を検討しながら問題点を見つける力を身につけ、「適切な説明文」が書けるようにトレーニングしていこう。

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

 仕様書、指示書、提案書、計画書等々、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行以下の文であれば考えるのにもそれほど時間はかからないはずだ。

※この続きは、会員の方のみお読みいただけます(登録無料)。


※この続きは、会員の方のみお読みいただけます(登録無料)。


著者プロフィール

  • 開米 瑞浩(カイマイ ミズヒロ)

    東京大学理科一類中退。IT技術者の業務経験を通して「読み解き、考え、説明する」スキルの再教育の必要性を認識し、2003年からその著述・教育業務を開始。小説家を目指したほどの文章力にもかかわらず図解を多用し「文章は図解の添え物」との主張が持論。図解力、思考力、プレゼンテーション等の講師として民間企業・...

バックナンバー

連載:例題でわかる! 伝わるドキュメントの書き方トレーニング
All contents copyright © 2007-2019 Shoeisha Co., Ltd. All rights reserved. ver.1.5