SHOEISHA iD

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

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

最新イベントはこちら!

予期せぬ事態に備えよ! クラウドで実現するIT-BCP対策 powered by EnterpriseZine

2024年7月10日(水)オンライン開催

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

お申し込み受付中!

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

文章を書くな、ラベル付きステートメント構造を使え

一瞬で情報を読み取る手がかり満載のスマートな箇条書き法


ドキュメントを書くのが苦手だから「文章力を上げたい」と考えるエンジニアは少なくないが、ドキュメント力は文章力とイコールではない。実は、わかりやすいドキュメントを書きたいのなら、そもそも「文章を書かない」ほうがよいのである。エンジニアが書く仕様書や説明書は、小説や報道記事とは違う。そこに求められる最適な表現形式やノウハウも違ってきて当たり前なのだ。 今回は、「箇条書き」をよりスマートにした「ラベル付きステートメント構造」を使う習慣を身につけよう。ちょっとした工夫ではあるが、これだけで「短時間で正確に読み取りやすい技術ドキュメント」を書くことができる。しかも、わけのわからない「文章力」というスキルは必要ないし、にもかかわらず文章の読解力も上がってしまうという一石二鳥、三鳥の方法なのである。

ラベル付きステートメント構造を使え

 さて、「日本語による説明文(数行程度の短いもの)」の品質向上を目的として、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. ステートメントは「1つの意味だけを表現する」ように極力短くする
  2. ステートメントの記述順序に注意し、意味のある順番にはナンバーを振る(Step1、Step2などがその部分)
  3. ステートメントには極力「ラベル」をつけるようにする

 注意点A項について補足しておこう。「ステートメント」という概念を私は「1つの意味だけを明確に表現した短い文」という意味で使っている。要するに文章術のノウハウでよく言われる「一文一意」(ワンセンテンス・ワンミーニング)を守って書いた1文のことである。

 仕様説明文でこのようなラベル付きステートメント構造を使うことには大きなメリットがある。ここで、出題例文と改善案を見比べながら、どんなメリットがあるかを考えてみよう。

次のページ
ラベル付きステートメント構造は短時間で「解読」できる

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

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

もっと読む

この記事の著者

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

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

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

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

この記事をシェア

EnterpriseZine(エンタープライズジン)
https://enterprisezine.jp/article/detail/142 2007/10/12 13:16

Job Board

AD

おすすめ

アクセスランキング

アクセスランキング

イベント

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

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

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

メールバックナンバー

アクセスランキング

アクセスランキング