SHOEISHA iD

※旧SEメンバーシップ会員の方は、同じ登録情報(メールアドレス&パスワード)でログインいただけます

EnterpriseZine(エンタープライズジン)編集部では、情報システム担当、セキュリティ担当の方々向けに、EnterpriseZine Day、Security Online Day、DataTechという、3つのイベントを開催しております。それぞれ編集部独自の切り口で、業界トレンドや最新事例を網羅。最新の動向を知ることができる場として、好評を得ています。

最新イベントはこちら!

EnterpriseZine Day Special

2024年10月16日(火)オンライン開催

EnterpriseZine(エンタープライズジン)編集部では、情報システム担当、セキュリティ担当の方々向けの講座「EnterpriseZine Academy」や、すべてのITパーソンに向けた「新エバンジェリスト養成講座」などの講座を企画しています。EnterpriseZine編集部ならではの切り口・企画・講師セレクトで、明日を担うIT人材の育成をミッションに展開しております。

お申し込み受付中!

例題でわかる! 伝わるドキュメントの書き方トレーニング

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

その処理の名前は何ですか?


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

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

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

次のページ
その処理の名前は何ですか?

この記事は参考になりましたか?

  • Facebook
  • X
  • Pocket
  • note
例題でわかる! 伝わるドキュメントの書き方トレーニング連載記事一覧

もっと読む

この記事の著者

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

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

※プロフィールは、執筆時点、または直近の記事の寄稿時点での内容です

この記事は参考になりましたか?

この記事をシェア

EnterpriseZine(エンタープライズジン)
https://enterprisezine.jp/article/detail/15 2007/09/11 13:01

Job Board

AD

おすすめ

アクセスランキング

アクセスランキング

イベント

EnterpriseZine(エンタープライズジン)編集部では、情報システム担当、セキュリティ担当の方々向けに、EnterpriseZine Day、Security Online Day、DataTechという、3つのイベントを開催しております。それぞれ編集部独自の切り口で、業界トレンドや最新事例を網羅。最新の動向を知ることができる場として、好評を得ています。

新規会員登録無料のご案内

  • ・全ての過去記事が閲覧できます
  • ・会員限定メルマガを受信できます

メールバックナンバー

アクセスランキング

アクセスランキング