はてだBlog(仮称)

私的なブログど真ん中のつもりでしたが、気づけばWebサイト系のアプリケーション開発周りで感じたこと寄りの自分メモなどをつれづれ述べています。2020年6月現在、Elasticsearch、pandas、CMSなどに関する話題が多めです。...ですが、だんだんとより私的なプログラムのスニペット置き場になりつつあります。ブログで述べている内容は所属組織で販売している製品などに関するものではなく、また所属する組織の見解を代表するものではありません。

ドキュメンテーションのコツのラスト1マイル

はじめに

ドキュメンテーションやドキュメントを元にした合意形成や他者への動機付けのアプローチについてご高説をたれてみます。

最近はドキュメンテーションのテクニックや手法は数多く有効な方法が提唱されていると思いますが、あともう一声言ってほしいな・知りたいなというところについて、私の探した範囲では、見つけることができませんでした。

私だけかもしれませんが、このあと一言の部分にたどり着くまで、随分苦労しました。

もしかしたら同じようなところで迷っている人がいて、しなくて良い苦労をしているのであれば、なんらかのヒントになれば良いと思ってここに3点あげてみました。

私の経験上、エンジニアリングの周辺を意識した部分が滲みでていますが、いまや世の中、総ITなので、ある程度は他の分野にも当てはまると思います。

あと、このドキュメント自体が、自己矛盾しているところはあるかもしれませんが、そこはご容赦(汗汗)。

1. 価値感度を探る

人は言います。ドキュメントは相手に応じてストーリーや説明の仕方を工夫しなさい。

しかし、相手に応じてというのはなんだろうと思います。

私は相手の価値観をつかむことが重要だと思います。

f:id:azotar:20181210211133p:plain

2. 相手の納得や常識のモノサシを見極める

人は言います。ロジックが必要だ。

しかし、ロジックってなんだろう。

私は、皆が言うロジックというものは、むしろロジックではなく、モノサシのようなものだと考えるようになりました。

f:id:azotar:20181210211204p:plain

この人のモノサシはなんだろうというところに注目してみてください。

3. 何を説明するか

人は言います。メッセージがはっきりしない。

ところが、メッセージをはっきりさせたとしても、ぼんやりしていることはありませんか。

例えば、文字サイズが大きいことは気持ちが良いですが、むしろ胡散臭くなったり、主張は以前としてはっきりしない、あるいは目に飛び込んでくる主題の一文と挿絵がしっくりこないということがないでしょうか。

全てにあてはまるわけではないですが、メッセージを説明する方法にメリハリがない場合に、このようになることがあるような気がします。

意外なことですが、全てを説明する必要はありません。メッセージをはっきりさせるとともに、説明内容を絞りましょう。

f:id:azotar:20181210211252p:plain

なお、(端的に)見える化するのは思ったより有効だと感じています。

上の図で4つあげたものの中では、一番、手抜きに見えるにもかかわらずです。

例えば、 f:id:azotar:20181210212618p:plain

ですが、

それ自体が根拠を十分に含んでいるような「事実」が揃っていれば、見える化だけで相手が察してくれるのです。 (「です。」と言い切りましたが.... 笑)

ロジカルシンキングせよ、ロジカルに説明せよと言われると真正面から向き合ってドツボに入ることがありますが、意外にもロジックに入り込みすぎない方が良いというのは、ドキュメント作成にはいろいろあてはまるような気がします。

逆に言うと、「事実」をしっかり見極めてそのようなデータが手にはいれば勝ったも同然です。

(まあ、そんな都合の良い「事実」がデータの形で転がっていないのも事実ですが...)

まとめ

ドキュメンテーションで、言われれていることはわかるけど、具体的にはどうすりゃいいの? というときに、踏み込んでみたら良いかなと思うポイントを3つあげてみました。

ドキュメントは人を動かしたり、自分自身を客観視するには有効な方法ですが、一方で所詮絵に描いた餅にすぎないところもあります。

逆に言うと、ドキュメントの些末なところで時間を取れられるよりも、ここにあげたようなポイントに注目することで、ドキュメント仕事をさっさと終わらして本題に入れるようにしたいところです。

そういえば、似たテーマで、 以前ロジカルシンキングについて主張していたことを思い出したので、しまりそうで締まりませんが、最後にリンクしてみます。

itdepends.hateblo.jp