読者です 読者をやめる 読者になる 読者になる

報告書において文章で説明できないことを図で書いて説明したことにするのはダメ

理由は、その図の解釈は読者ごとにぶれるから。少なくとも著者がその図を用いて何を説明したかったのかについては解釈の余地を残さずにきっちりと説明していないといけない。その説明を超えたことを図から読み取るのは読者の自由。と、以下のエントリーを読んで追加的に思った。

循環構造を解消するためのテクニックのひとつに、各項目を分解するということがあげられる。言語の入門書の場合は、だいたいの項目が、利用と作成にわけられる。メソッドの場合は、メソッドを呼び出すことと、メソッドと定義することにわけられるけど、最初のうちはすでに定義されたものを使うことにすれば、定義に関しては後回しにできる。クラスなども同様だ。

このようにして、閉路のある構造グラフを、閉路のない構造グラフ、つまりツリー構造に変換する。

循環構造を解消できれば、あとはツリー構造をたどる優先順位の問題になる。基本的には、このツリーを全探索するということになる。このとき、幅優先でいろんな項目をかいつまんで説明するよりは、深さ優先でひとつひとつを説明しきって行くほうがいい。

私の好み&説明方針からすると、幅優先で全体像を把握してもらったのちに、深さ優先で説明を試みる。せっかくツリー構造にしたのに、そのツリーの構成を説明に使わないともったいないというのが私の好み。説明項目の階層化を行うときには、説明を行う際の観点を決めると良い。代表的なのは以下の観点。

  • 抽象的から具体的
  • 概略から詳細
  • 過去から未来
  • 外観から内部
  • 大きいものから小さいもの

話し戻って、ダメな図とはどういうものかといえば、報告書の理解を助ける役目を果たしていない図がダメな図(同様に、ダメな表、式、例題、疑似プログラムもこの定義)。どうして、ダメな図を書いてしまうかといえば、その図によって何を説明したいのかをはっきりさせていないから。なので、 きしだのはてな:文章に向いてない構造をいかに文章に向いた構造に直列化するかが大事で言われている

「それは文章で書くべき情報なのか」という章があって、直列化した論理構造であれば文章には書きやすいけど、分岐やループがあるような構造だと書きにくいということが書いてあった。そこで文章化しにくい構造の例として地図があげてあって、暗にそういう構造は文章化をやめて図であらわせと言っているように読める。

けれども、図に書いたところで、書く側は文章化から逃げれて満足かもしれないけど、それを読み取る側は結局どこかから順番に解釈していく必要がある。図に逃げるのは、読み手に責任を押し付けているだけだと思う。

には賛成。たぶん、文章で説明できない図のほとんどは、その図で何を説明したいのかがわからない図になっている。

同じ事柄を説明したいとしても、観点によって図は大きく変わる。制御を説明したいならば制御フロー図やフローチャート、データの流れを見せたいならデータフロー図、二者間のコミュニケーションを示したいならシーケント図など説明したいことによって、適切な図は異なる(そもそも、図を使った方が良いのかという点から検討が必要)。

とりとめもなくなったのでまとめると、報告書において文章で説明できないことを図で書いて説明したことにするのは以下の理由で良くない。

  1. 図が何を示しているのかを説明しない場合、著者が想定していたのと異なる解釈が行われる場合がある(誤解を招く)
  2. 文章で説明できない図は往々にして理解の役に立たない