説明上手道（せつめいじょうずどう）
きれいなコードを書く子が醜いドキュメントを書いているのを見ると悔しくなってきます。どうして読みやすいコードを書くときと同じ思考をドキュメントを書くときにしないのかな。
ドキュメントは人が読んで理解するためのものだけど、「仕様書」「設計書」& 責任分散なウォーターフォールモデル開発だと、どうしても言質をとった・とらない（仕様を網羅したか）の証拠物件になってしまいます。そういう世界の「常識」をひきづって、人が理解しにくいドキュメントをつくって、それが原因で仕様認識齟齬が生まれているプロジェクトの現状を見る度、なんだかなぁ、と思ってしまいます。仕様書の本分は仕様をみんなに理解してもらう為のだから、正確さと同じくらい わかりやすさが肝心ですよ♪（と、思うのですよ）
そうはいっても、人に何かを理解させることは大変です。青木さんのSmalltalk本（だったかな？）に、「脳を直接私と同じ構造に作り替える」じゃなくって「メッセージを送ること」しかできない、とあったけど、まさにその通り。単に知っていることを投げつけるだけではダメで、レシーバの事情を考慮しなくてはいけません（難しいなぁ）。他人の説明やドキュメントには文句はつけるあたしだけど、だからといって出来ているとは言い難いなぁ。(^^;
そんなあたしが、すごいなぁ、こうなりたいなぁと思うのが、カメラ系サイトhttp://www004.upp.so-net.ne.jp/cam/の我輩さん。どんなにすごいかっていうと、たとえばこれ。
この雑文のテーマは、「小さなCCD + 同等の画角になる焦点距離のレンズ」のセットが、決して 35mmフィルムや大きなCCDを使うのとは同等ではない、ということです。そんなテーマでこのタイトルなのに、いきなり
ピグミーマーモセットは、世界最小のサルである。体長は約14cm程度で、人間の手で掴めるほど小さい。また逆に、約30万年前には、体長3メートルほどのギガントピテクスという猿人が生きていたと言われている。両者の体長を比較すると、20倍もの違いがある。
で始まる導入は、ちょっとびっくりするのです。しかし焦点距離と被写界深度の話を経由したとき、この無駄だと思えるような冒頭のネタふりが、（ネタバレになるので具体的には書きませんが）話の最後で見事に合流したとき、科学的な「なぜなに」を淡々と説明するよりも、遙かに鮮やかに「ああ！そういうことなのか！！」と理解することができるとても見事な構成です。上手な比喩と上手な文章は恐るべき威力するっていう好例ですね♪
「如何に事実を正しく書くか」ではなく「如何に事実を正しく伝えられるか」が大事なのだなぁ。この方の雑文みたいなのがポンポンかけるようになれれば良いのですが。精進しなくっちゃ。
