今、会社で隣の席に昨年の新人君が座っています。プロジェクトとプロジェクトの合間で本社に戻ってきてるだけなんだけど（うちは基本的に客先常駐）。で、せっかくなんで色々教えてたりするわけです。
で、教えたことを書類に纏めてもらったんだけど、これが読みづらい。なんでかな〜、って考えて2つほどポイントを教えた。
文章を構造化しよう
読みやすい文章は、上手く構造化されている。章や節、見出しなんかに統一感と構造がある。例えば、彼の文章は最初こうなっていた。
1. ほにゃららら
2. ふにゃららら
3.1 へにゃららら
3.2 ぐにゃららら
4. へぎゃららら
4.1 どりゃららら
マテ、と。見出し番号の振り方おかしいよ、と。とりあえず、こうしとけと伝えた。
1. ほにゃららら
2. ふにゃららら
3. たらららら
3.1 へにゃららら
3.2 ぐにゃららら
4. へぎゃららら
4.1 どりゃららら
ちゃんと構造化されてるかどうかは、多分ですが、検索の容易さに関わってくる。コンピュータによる検索ではなくて、人間の目による検索。どこに自分の読みたい情報があるのかを瞬時に判断するために、文章が統一感をもって構造化されていることが重要。
一文を短くしよう
分かり辛い文章を書く人は、やたらと難しく長い文を書く。一つの文は短い方が良い。人の頭へかかる負担が、格段に減るから。
Aは、Bであり、Cであるので、DまたはEだと言える。
こんな文で言いたいことは、「Aは、DまはたEである」なのだ。その結論に到達するまで、「Aは」「Bであり」「Cである」という情報を頭の中に記憶しておかなくてはならない。これって、文が長くなると中々に大変。すぐに理解できるような文になりません。
Aは、Bであり、Cである。だから、AはDまはたEだと言える。
または
Aは、DまたはEだと言える。なぜなら、Bであり、Cであるからだ。
と書いた方がいいんでわないかと。文を短くして、接続詞を適切に使ってあげればいいのだ。その方が正しい文を書くのも楽になる。
まぁ、私自身、あまり文章を書くのが上手いわけじゃないんですが、それでもこの程度のことは言える。逆に言うと、この程度のことすらできない人が多いなぁ、と。エンジニアがお仕事で書く文章は、なるべく誤解を与えないようにしないと。