開発ドキュメントの「説得力」を磨く5つの鉄則、図や表の上手な使い方

　分かりやすく説得力のある文章や図表を書くうえで特に重要な5つの鉄則のうち、前回は（1）最初に構成を考え論理性を高める、（2）意味のあいまいさを排除する――の2つを解説した。

　今回は、（3）文章と図表をバランス良く用いる（4）レイアウトの工夫で視認性を高める、（5）無駄取りと切れ目でリズムを整える──の3つを順に見ていこう。

鉄則 3
文章と図表をバランス良く用いる

　ドキュメントの分かりやすさを高めるうえで、図表が大きな効果を発揮するのは、誰もが実感していることだろう。しかしDFD（Data Flow Diagram）やクラス図といった設計用の図、さらに業務フローを表した図を除けば、「文章による説明で終始しているケースが少なくない」と中堅ソフト開発会社のN氏は指摘する。

　N氏によれば、特に図表による説明が求められるのは、システムの利用部門における業務のやり方のルール（ビジネスルール）説明だという。「商品の種類によって異なる配送方法、得意先だけに適用する在庫引当といったように、ビジネスルールは組織によって千差万別である。きちんと把握するには、業種業務の知識も必要になる。文章だけでなく、図表を使って明確に表現することが極めて重要だ」（N氏）。

　そこで、ビジネスルールを表した2つの図表を紹介しよう。1つ目は、ビジネスルールに基づく出荷伝票の分割機能を説明したものだ。次の図の上半分にある文章を一読してみてほしい。機能の説明と、その理由となるビジネスルールが入り交じっているうえに、一部あいまいな記述があるため、すんなり頭に入ってこないだろう。

表を使った分かりやすい表現の例

文章だけではたとえ正確に書いてあっても、読み手が理解に手間取ったり、誤解したりしかねない。伝える内容が複雑かもしれないと感じたら、図表として整理できないか考えたい。ちょっとした図表でも、読み手にとって理解しやすくなることが多い

[画像のクリックで拡大表示]

　この文章を表を使って書き直したものを図の下に示した。表にしたことで、出荷伝票の分割の仕方が区分①～④として明確になった。また①～④の区分で出荷伝票を分ける理由を明記したことで、理解が深まりやすくなった（図の赤字部分）。

単純な図表で分かりやすさは段違い

　もう1つの例として、メーカーの情報システム子会社に務めるS氏が作成したドキュメントを次の図に示す。これは、商品在庫の引当場所によって顧客までの配送経路を変えるというビジネスルールを表したものだ。

商品の流れを図で説明した例

商品在庫の引き当て場所と配送経路の関係を表す図。このように、モノや情報の流れ、何かの関係を表すときには図として表したい

[画像のクリックで拡大表示]

　最初に、S氏は箇条書きで表してみたが、改善の余地を感じたという（図の上）。「複雑な内容ではないが、文章だと読み手自身が頭のなかでイメージを図として描かなければならない。ならば最初から図として表せば、直感的に分かり、読み間違えて誤解する危険性も減ると考えた」（S氏）。改めて図を使って表したのが図の下である。引当場所ごとの配送経路が直感的に分かる。

　このように、モノや情報の流れ、何かと何かの関係を表すときなどは、図として表すことを考えるべきだ。前述した2つの例からも分かるように、ちょっとした図表でも、文章だけの説明に比べて分かりやすさが格段に高まる。

　ただし図表を作成する際に、気を付けたいことがある。それは、図表だけで説明を完結させるのではなく、図表の見方や補足情報を表す文章を入れることである。SIerで公共向けシステムの開発を手掛けるT氏はこう指摘する。「文章による説明がない図表だと、どう読めばいいのか分からないことが多い。文章と図表のどちらかだけで表現するよりも、両方をバランス良く使って説明するほうが分かりやすくなる」。