読み手のコンセンサスを得たければ読み手が好き勝手に読む権利を持っていることを理解することが必要です

設計書の目次構成や文書に差し入れるポンチ絵のような図はその文書で執筆者が主張したい考えや理論を助けるためのものです。文書として、資料として執筆者が考えた思いを表現として明示化したものであるともいえます。つまり、イコール頭の中をさらけ出しているようなものです。

よって、文書の構成や図は読み手となる人全員が理解できなければなりません。

ところが、その目的を知らないのか意識ていないのかわからないけれど、まったくもって執筆者として記述内容を理解してもらう権利を放棄しているとしか思えない文書を量産するエンジニアが少なからず存在するのですよね。

幸か不幸か、そうした執筆者の周りの人たちは、そうした執筆者の説明と言う文書の行間の情報を補てんされて説明を聴くことになるので文書としては不格好のままで刷り込まれてしまうのです。だから、そうした文化のあるチームが出来上がるとそのチームの中にいないとわからない暗黙の知が生まれてしまうんですね。

こうした一度根付いた文化はそうそうとかわらないんですよね。そして、このように根付いてしまったことで、文書の目次構成や挿絵となるポンチ絵などの図が本来の目的とするところを達することが出来なくなるわけです。

文書の目次構成や図の目的は、それの読み手が全員理解できることです。

執筆者が表現する表記法が直感的で読みやすくなければそれらを満たすことはできません。例えば図を差し入れる文書の目的によって、図はカラフルでデザインに意味を持つアイコンを使用する方が理に適っていたり、図のアイコンに意味を持たせてしまうと逆に情報過多となりアイコンから情報を理解するプロセスが余計に入り込むことで文書を理解するという所作を妨げることだってあるのです。

言い換えると、図ひとつを取っても、文書の理解を促進したりすることもあるし、いくつかの理解方法を示したりすることで理解を妨げることもあるのです。

文書の理解を助けるはずの図が正しいかどうかはその図が表す現物を確かめればいいのですが、現状存在しない、新規で開発するソフトウェアのようなものは、存在しないのだから確かめようがないのですね。であれば、尚更、文書で主張したい事柄について意図のとおりに理解できるような表現法を選択しなけければならなくなります。

さて、どこまで文書の目次構成や挿絵の図がその目的を達しているか身のまわりの設計書や資料を幾つかサンプリングして確かめてみると良いです。

まったくもって考慮されていないことが多いですから。その理由の一つには、執筆者が文書なり資料なりを作成するときに前提条件や仮設としておいた条件を明示していないから、たったそれだけ、なんですよね。

だから、文書や資料を読む際に執筆者自身の解説として補足を必要とするし、アイコンに秘められた(！)意図を汲み解釈しなければならなくなるのです。

とは言え、目次構成も挿絵の図も表現法自体は文書で主張するための必須条件ではありません。だから、アイコンが絶対だめなのかといえば、凡例を伴うのであれば設計書で差し込むことは返って理解を促進したり、シンプルにフローチャートのアイコンで表現してもいいわけです。

単純な話、補足が必要なら必要となるときに補足すればいいのですが、ページを読み進めれば人は自分で考えたこと以外は忘れてしまうということを強く認識しなければならないということです。そしてそのこと自体を執筆者自身が忘れてしまうのです。

こうした目次構成で表される執筆者の思考や図などで表現する表記法は読み手が必要なときに必要な情報を得られないのであれば、執筆者が主張したい事柄についてのコンセンサスを得ることは読み手に解釈を与えるため結果的に難しくなります。

執筆者は、書き手が書きたいと思うように読み手は読み手で好き好きに理解しながら読むことを肝に銘じなければなりません。それを忘れて読み手がベーシックなことを質問してくるコトに対して説明を面倒くさがったり、何度も質問する読み手に対してバカにしてはいけないのです。

すべては執筆者に対して返ってくるだけなのですから。