レベルエンター山本大のブログ

面白いプログラミング教育を若い人たちに

理解してもらうための文章 10ヶ条

あなたは12歳の4月1日午前ごろに何を考えていましたか?

と聞かれても何も浮かばないが、

中学校の入学式で何を考えていましたか?

と聞かれると、様々な記憶が呼び起こされる。


人間は、仕様や定義、数値といった情報を理解するようには出来ていない。


だから、読んで理解するための書き方と、物事を定義する文章の書き方は異なる。


定義する書き方の文章とは、たとえば設計書だ。矛盾が無く、漏れが無いことを重んじる。
また、書き手の個性が反映されてしまうと成果物として成り立たない場合があるので判で押したような文章で書く。
でないと書き手が変わったときにニュアンスを合せるのに苦労する。


しかしながら、こういった文章は読みにくいし理解しにくい。


最近僕は、作ったプログラムを説明するドキュメントを書いている。
これは設計書のように形式的なものではなく、
理解してもらうことが唯一の目的というドキュメントだ。


読んで理解してもらうための文章を書く場合は、次のようなポイントに気をつける。

1)読者が1から10まで理解するように書くのではなく、4まで理解できるように書く。

 4までというのは、「そこまで理解できたら、あとは自分で読み解ける」というレベルだ。

2)大雑把な説明から書きはじめる。詳細を補足していく。

 正確さと理解しやすさはしばしばトレードオフになる。
 正確さを求めると理解しにくくなる場合は、あえて詳細化せず抽象的にとどめる。
 ただし、ウソを書かないことだけは徹底する。

3)何を書かないかを決めて書く。

 何を書くかも大事だが、対象が決まっているなら
 何を書かないかという視点で書いてみる。
 書かないことで、書いた部分が浮き上がる。

4)見出しで4割を語る

 パソコン上で読む文章は、飛ばし読みされるものである。
 だから見出しが重要だ。見出しで4割を語る。
 見出しの次の1行で8割まで持っていく。
 「これから読み進めるものは何か」を説明することは、読みやすさの面で大きな効果がある。

5)話の展開に困ったら見出しを分割する。

 見出しを細かくするというのも、飛ばし読みを補助する上で効果が高い。
 経験則では、話の展開に困ったら見出しを分割してみると、話が進めやすくなる。

6)図、表、キャプチャには、短い説明文をつける。

 飛ばし読みが前提なので、図や表は良いアピールになる。
 図表には必ず表タイトルをつける。
 表を使うのは「表タイトルを読んでもらうため」というぐらいに考える。
 図、表、キャプチャには、短い説明文をつける。
 これは見出し以下1行目と同じ効果がある。

 たとえば現場では、SQL実行結果をExcelに落とした資料をよく作るが
 たいてい後で見ても意味が判らない。
 1行の説明文をつけているだけで全く印象が変わる。
 

7)アイコンを張るだけでも図になる。

 飛ばし読みが前提だから、注意を引きたい部分に、
 内容に関連するアイコンを張るだけで見栄えがする。 

8)トーンを変える。

 定義書のように、全ての情報を同じトーンで書いてしまうとニュアンスが伝わらない。
 色や文字の太さ、記号などでも強弱を作れるし、文章の冗長さでもトーンを作れる。

9)空白を活用してトーンを変える。

 箇条書きは、空白の活用の一種。
 箇条書きだけの文章は読んでも理解できないが、
 連続する文章の中に箇条書きがあれば目に留まる。
 

10)重要なところは、別の角度でもまとめる。

 定義書だと、メンテナンスがウザいから1度説明したら終わりにしがちだ。
 しかし理解するための文章では、何度も言い方を変えて説明してよい。
 1つの説明文章にごちゃごちゃ書くと焦点がずれる。


こうやって書くとブログエントリのためのよくあるまとめと同じだなぁ。