文書の作り方について思ったことのメモ。
手順書とか規約とか、正確さが要求される類の文書は、用語の使い分けを明確にして、誰が読んでも解釈に揺らぎが生じないように書く必要がある。
っていう通念はあると思うんだけども、最近思うのは、読み手が厳密なリーディングマシーンであることを想定しちゃいかんなということ。
ええとつまり一言でいえば「読みやすいように書きましょう」というだけの話なんだけど、しっかり読めばしっかり矛盾なく解釈できるようにすじが通っていて、かつ、ゆるく流し読みしただけでもざっくり理解できるように書く、というのが理想かなと。
自分でよくやってしまうのは、よく似た固有名詞AとBを用いて、Aがうんたら、Bがうんたらと書いて、自分では明確に使い分けてるからあとは読み手の問題よ、的な手口。
で、やっぱり読み違いを読み手の責任にするのは不親切だな、と思い直した次第なのでした。
ついでにいうと、プログラマーにとってはコーディングのときに全く同じことを意識するので、すでに馴染みのある話だったりする。
「書いたとおりに動く」コードより、「読んだとおりに動く」コードになるよう意識しましょうというやつだ。
ソフトウェアのソースコードというのはまさに、厳密なマシーンも読むし不正確な人間も読む文書であって、そのどちらにとっても同じ解釈ができるように書くことを、賢明なプログラマーであれば常に意識しているはず。
たとえば、ルーチン（関数）には処理内容を正確に表現できる名前をつける。
get_nameという名前の関数が名前でなくて住所を返す作りになっていたとしてもマシーンにとっては特に問題ないが、人間だったらほぼ確実に誤読するだろう。
たとえば、全く同じ内容のコードをあっちこっちにコピーして書かない。
100行から成る処理のうち1行だけ差異のあるコードが2か所に書かれていたら、その差異を見つけ出すのは難易度の高い「まちがいさがし」だ。
日本語（その他自然言語）で文書を作る際にも、同じことが意識できる。
関数名は段落の見出しと同じだ。
何度も言及する必要のある内容は、どこか1か所にだけ書いておいて、他の場所からは「○○を参照」とリンク付けすれば良い。
そんなことを考えてたら、fladdictさんが「ざっと見る」「じっと見る」という観点からUI設計の考察をされていて、これもちょっと似た話だなと思ったりした。
こんなふうに、ひとつの分野で得た知見が他のいろんな分野に応用できるなって思い至ったときに、あーこういうのがつまり「原則」ってやつなんだなと気づいて、新しい道具を手に入れられた気持ちになるのよな。
Related:
