ドキュメントは冗長でないとわかりにくい

プログラマにはドキュメントを書くのが下手というか苦手な人が多い。苦手というのはちゃんと書いたつもりなのに、理解してもらえないということだ。

単純にドキュメントを書くには違うスキルが必要だから、と言ってしまえばそれまでだが、いったい何が違うのだろうか。

ちょっと考えてみると、プログラマはプログラミングが本業である。プログラミングは、なるべく冗長な部分を減らすような思考になる。そしてドキュメントをその考え方のままで書くと、冗長性の少ない、（プログラマにとって）素敵なドキュメントが出来上がる。

冗長性の少ないドキュメントは、関連性が最小限に押さえられていて、リファレンスとしては過不足ないにしても、読む側は取っ掛かりがなくて非常に辛い。

ある部分は冗長に記すことで読む人の記憶に焼き付けさせ、必要ない部分は思い切って省略することで読む人の注意を分散させないという強弱加減も、ドキュメント記述の上では大事な要素だ。

どこを重要とするか。どこを切り捨てるか。このあたりの取捨選択っぷりがドキュメントのよしあしを決めるのではないか。

プログラマが重要と思っている部分は、わりと技術寄りで高度で難しいけれど、本当にソフトウェアのことを知りたいと思っている人にとっては、どうでもいい部分である場合が結構ある。

なので、プログラマがドキュメントを書かないといけなくなったら、何が重要と思うか、プログラムを作っていない人に聞いてから書き始めるのがよいのではないかと思う。プロダクト作成には事前ヒアリングが大事ということだ。