ドキュメントの目的を間違えていないか

スキル

» 2017/04/03

手順はドキュメントだけでは伝わらない

　最近、ツイッターを見ていたらマニュアルに関する話題で盛り上がっていた。何かマニュアルに関する事件でもあったのだろうか。ドキュメントをよく書く立場としては非常に気になった。エンジニアというのは、取り組む対象が技術だ。否が応でもドキュメントと関わることは避けられないだろう。

　ちょっとツイッターの呟き眺めていて気になったことがある。普通の人は、「マニュアル通りやったらできるはずだろ」と口にする。テレビでもパソコンでも、これさえ読めが使いこなせる。そういうものを求めているように思う。まぁ、使い方自体が簡単なものなら、一度読めば使いこなせる。そういうマニュアルも存在するだろう。

　しかし、ちょっと多機能な電化製品にでもなると話が違ってくる。まず、マニュアルが分厚い。読むだけで一苦労だ。そもそも、使いたい機能について書かれたページを探すだけでも大変だ。「マニュアル読めばできるだろ」とさも当然のように語られるが、実際にそうなった試しが無い。

　ソフトや機器に付いてくるドキュメントはじっくり読むようにしているが、かなりの時間がかかる。それでも、急いでいたり、分からない時はサポートに頼る。また、ドキュメントを読むだけではなく、実際に操作したり、弄ってみたりと、必ず試行錯誤もする。ドキュメントを読むだけで全部できるほど現実は甘くない。

ドキュメント一つでどうにかなるほど甘くない

　ドキュメントをよく書く人であれば分かると思うが、事細かく書けば書くほど、ドキュメントの量は増える。詳しく書けば、分かりやすくなる代わりに分厚くなる。分かりやすさと分厚さはトレードオフだ。また、いくらでも事細かに書けるものでもない。ある程度の複雑さがある以上、簡単にするにも限界がある。情報の絶対量が多ければ、読むだけでも相応な労力になる。

　それでも簡単にしたいと言うなら情報を省くしかない。必要な内容に絞り込んでドキュメントを書くしかない。そうしたらそうしたで、「これ一冊で必要な作業が全部できるのか」とツッコミが入る。工数も無い、分かりやすく書け、分かり易く書くと分厚くなる。「これを読めばどうにかなる」という要件を真に受けると、大体の人はドキュメントを書くのが嫌になるか苦手になる。

　ドキュメントを書く時は、必ず条件を書くようにするといい。手順なら、どういう時に使う手順か、前提になる設定や状況を手順の前に書いておく。設定内容を書くにも、設定の意図を書いておく。こういった条件を曖昧にして、安直に図解で説明するのは最悪な書き方だ。まずは条件を絞り込もう。ドキュメントはかなり書き易くなるはずだ。

　「これを読めばどうにかなる」というドキュメントが書けないのは、条件が常に変わるからだ。例えば、「絶対に彼女のできる本」というのを書いたとする。本の内容は変わることはないが、読む人がイケメンかブサイクかという条件は変わる。条件が変わることで、本の内容が通用しなくなるケースも出てくる。ドキュメントだけでどうにかできるほど現実は甘くない。

ベストプラクティスは変化する

　ドキュメントで条件を書くことが有効なのは分かると思う。しかし、条件は常に変わる。もし、条件が変わらないような定型作業なら、ドキュメントを書くよりプログラムを書いて自動化する方が早い。また、人が何かをやる上で想定外はつきものだ。想定外を全て予測してドキュメントを書くのは不可能だ。

　条件が変わると、それに合わせて必要な手段も変わる。ドキュメントを書くとなると、想定する条件の数が増えるほど、書くべき内容が増える。不安に任せて想定する条件を増やしすぎると、書く内容が増えすぎてベストプラクティスが逆に分からなくなってしまう。書いたはいいが、使わない内容が増えすぎて、見通しの悪いドキュメントになってしまう。

　ベストプラクティスは手段と条件の最適な組み合わせだ。条件は数を出すより絞る方が、最適な手段がどれか分かり易くなる。ドキュメントで大事なのは、どういう条件で書かれているかだ。条件をはっきりさせることと、どういう条件を選ぶかがドキュメントの質を決める。ダラダラと細かく書くだけではドキュメントの質は上がらない。

　条件は常に変化していく。ドキュメントで想定した条件も、時間や状況が変わることで通じなくなることもある。残念ながら、それを避ける方法は無い。条件が合わなくなったと感じたら、中身を見直してドキュメントを更新するしかない。条件が変わればベストプラクティスも変わる。ドキュメントを書く以上、このことは肝に命じておこう。

ドキュメントは思索するための道具だ

　ドキュメントを書く上で条件を選ぶのは難しい。ただ、最適解をいちいち模索するから難しい。判断基準になるレベルで十分だ。そういうドキュメントなら気軽に書けるはずだ。そのくらいの気持ちでもないと、長編のドキュメントは書いていると心が折れる。

　レイアウトに凝っても意味はない。言葉で説明できないことを図解にしても、分かりやすくなるどころか、余計に意味不明になるだけだ。構成が破綻してるドキュメントは、だいたいExcelで統一性の無いレイアウトで書かれている。中身の無いドキュメントほど図解に走る。テキストでもいいので、条件と手段を結び付けて書くことが一番重要だ。

　ドキュメントの存在意義は条件と手段のセットが書かれていることだ。条件が書かれていないと、判断の材料として使えない。記録なら5W1Hを揃える必要がある。ドキュメントなら要件や必要な前作業、必要なコンポーネントのリスト等、いろいろな条件があるはずだ。何故これらが必要かと言えば、考えるために必要な情報だからだ。

　一回読んで全てを理解できるドキュメントを目指しても、永遠に実現できないだろう。どれだけのことが理解できるかは、読む人の知能に依存するからだ。分からないならドキュメントを何度も読もう。そして考えよう。ドキュメントの目的は考えるための材料だ。自分の欲しい正解は自分で見つけよう。自分で考える習慣が身に付いている人であれば、言っている意味が分かるはずだ。