ドキュメンテーションにまつわる問題。

先週の金曜日に、社内勉強会の講師を担当しました。
テーマは、「設計書ってどう書くよ？」
かなり幅の広いテーマだったので、テーマが決まってから
どう発表するか、悩んでいました。

事の発端は、「ドキュメントを本当に目的にそって、
作ることができているのか？」という提起。
ただドキュメントを作れば良いというものではない。
それは誰しもが理解しているはず。
しかし、書き手が、ドキュメンテーションの
目的(Why)、内容(What)、書き方(How)を本当に押さえられて
いるかは、確かに疑問を感じていました。

外部設計書＋内部設計書
＝書く手間を省いた設計書！スゴイ！
概念データモデル＋論理データモデル
＝書く手間を省いたモデル図！スゴイ！
という考えを実際の仕事で、垣間見えることがあったからです。

自分自身、ドキュメンテーションの5W1Hが本当に
出来ているかどうか、自信は無かったので、これを
良い機会と捉え、じっくり調べることにしました。

（しかし、テーマが広すぎて、焦点を絞り込むのに
とても苦労しました。）

ドキュメントを作る目的(Why)は、関係者間の
コミュニケーションと合意・納得を形成するためのものと
私は捉えています。
そして、ドキュメントの要件として、読み手が
理解できるものでなければならないというのは
基本的なことでしょう。
読み手が理解できない時点で、そのドキュメントは
作る目的を失っていると言えるのではないでしょうか。

ドキュメントは最も客観的なモノでなければならない
ものなのに、モノ書きである以上、主観が
非常に入り込み安いものですよね。
結果、書いている内容が訳が分からない、自己満足
なモノ、あるいは、きちんと整理されていない、
無駄なモノが出来ているだけ、ということにも
なりかねません。

コンテンツの書き方(How)まで、きちんと定義している
ベンダーが少ないことがその問題を助長しているの
ではないかと考えています。
Whatは定義されているケースは良くあるかと思います。
基本設計書として、画面レイアウト、画面遷移図etcを
用意しなければならない、といったように。

エンジニアは、このHowを自分の中で確立しておかなければ
ならない。そう考えています。
なんとなくではなく、本当に書けるのか？

というわけで、最初の提起。
「ドキュメントを本当に目的にそって、作ることができているのか？」

これの指摘している問題とは、
「そもそも目的を理解しているか？」
があり、さらに
「目的にあわせて、書けているか？」
があります。

勉強会は、発表のあと、熱い議論になったので、それなりに
実りにあるものだったのではないかと思い返しています。
しかし、この回の勉強会は、私より若手の人々に思いを伝えるのが
狙いだったんですが…。
なかなか上手く行かないものですね。