ドキュメンテーション - 要求分析駆動設計

参考書籍一覧（Amazon アソシエイトリンク）

各々の要求分析プラクティスでドキュメンテーションについては言及してきた。ここではドキュメンテーション全般に関することを話したい。

各要求分析プラクティスのドキュメンテーションは、顧客（プロダクトオーナー、ドメインエキスパート）と開発者のためのドキュメンテーションである。

通常、顧客はコードが読めない。
人は頭の中で大量の情報や複雑な関係を正確に維持し続けることもできない。
人は記憶が薄れ、思い違いをする。
人は異動するし、異動してくる。

人とは、顧客と開発者の両方である。

XPが背景にあるため、DDDではコードと会話が主役でドキュメントは脇役であるかのような主張がなされている。また、「コードがドキュメントだ」などという者もいる。私のスタンスはこういった考えと相容れない。

ドキュメントは少なくとも2種類あるということを理解しなければならない。それは、仕様のドキュメントと設計のドキュメントである。仕様のドキュメントは顧客と開発者が見て、システムを理解したり再確認するのに役に立つ資料である。ユースケースやビジネスルールの一覧、用語集、データディクショナリなどがそうである。設計のドキュメントは顧客が見ても役に立たず、開発者がアーキテクチャや物理データモデルを理解するために利用する資料である。

仕様のドキュメントがなければ、顧客が仕様を確認したくとも、開発者に解析を依頼するしかない。
仕様のドキュメントがなければ、顧客が仕様を俯瞰的に確認しようにもすべがなく、一貫性に欠けたり矛盾した仕様を発見するのが困難になる。
仕様のドキュメントがなければ、新規参画の顧客や開発者の立ち上がりを著しく阻害する。
仕様のドキュメントがなければ、状態遷移図やスイムレーンで図示できるモデルが把握困難か、最悪、解析しても把握できなくなる。

画面を見ればわかるようなドキュメントを用意する価値のない情報も当然ある。しかし、そんなものはごく一部なのであって書き残しておくべき価値のある情報は山のようにある。

設計のドキュメントは開発者向けであるから、コードを読めば把握できる情報というのは多くなる。それでも、アーキテクチャのような図示することで理解が容易になったり、コードからコンセプトが読み取れないようなものはドキュメントとして残す価値がある。

「ドキュメントは古くなる」という主張もあるが、古くなっていることに気づいたタイミングでアップデートをすればよいのであって、常に最新にしておかなくてもよいのである。アップデートするのは全員の役目だが、仕様のドキュメントなら参照頻度の多い顧客が主として行うことになるだろう。

また、上記は長期間利用されるドキュメントの話である。ユーザーストーリーのような賞味期限が1週間、2週間のドキュメントもあるし、DDDが想定しているようなホワイトボードやフリップチャートの代わりとして、目の前の問題を理解するためだけに作られるドキュメントもある。そういった短期的なドキュメントも、のちのち「なぜこの仕様にしたのか」「誰がこの仕様にしたのか」という記録として役に立つ時がくる。インデックスカードや会話とホワイトボードだったら、そんな記録はどこにも残らない。記録がなければ、仕様変更によって当初のコンセプトが破壊されるのを止めるチャンスもなくなってしまう。色覚異常の人のためのカラーデザインだったのが、デザイン変更によってそのコンセプトが破壊されるといったことが起きる。

以下の引用はコーディングに関することであるが、ドキュメントを書く理由としても適用できる。

■書き手の便宜よりも読み手の便宜を優先する

最初の開発時でさえ、コードを書くことよりも読むことの方が多い。読み手の便宜を犠牲にしてまで書き手の便宜を優先しても、表面的な節約にしかならない。

Code Complete 第2版上第6章クラスの作成 6.2.2 良いカプセル化

たとえあなたが副作用のあるステートメントを簡単に読めるとしても、あなたのコードを読むだれかに情けをかけよう。優秀なプログラマといえども、よく考えなければ副作用のある式は理解できない。彼らの脳細胞は、式の構文上の細かな点ではなく、コードのしくみより大きな問題について理解することに使わせよう。

Code Complete 第2版下第31章レイアウトとスタイル 31.5.4 ステートメントは1行につき1つ

コードにおいて、残す価値のないコメントというのは存在する。逆に適切なコメントや名前のためなら、時間をかけて考える価値がある。ドキュメントも同じである。だから、あらゆるドキュメントを作れとか考えなしに作れというつもりは毛頭ない。

顧客か開発者のためにあった方がいい情報か考えて書かなければならない。その情報が文章だけの表現で十分伝わるのか、図があった方がわかりやすいものなのか考えて書かなければならない。開発者向けなら説明箇所に適当に変更を加えたプルリクエストを出して、コメントをつける形でドキュメントを作ることもできる（ドキュメントのためのプルリクエストなのでマージせずにクローズさせる）。

また、役割ではなく個人の個性として、表現による情報の読み取りやすさが違うことも理解しておいた方が良い。文章だけで把握できる人、図の方が理解しやすい人、両方あった方がいい人、動かせるコードやプロトタイプがあった方がいい人、人それぞれである。

誰がドキュメントを書くのかということについて、顧客もドキュメントを書くと節々で言及してきた。「顧客」が一般的な意味での顧客で、発注者と受注者のような関係ならそのようなことは当然無理である。「金払ってるんだからお前らが書け」と言われるのがオチだろう。しかし、アジャイル開発においては、プロジェクトメンバとして参加する以上、お客様ではなくプロジェクトを成功させるために動く一人として行動してもらわなければならない。顧客の手抜きのために、口頭連絡やチャットでビジネスルールの変更を伝えるようなことはあってはならない。「こういうビジネスルールだったのがこう変わります」とチケットを切って、確定した段階でビジネスルールの一覧を更新するぐらいのことは情報の一次ソースである顧客がするべきだ。上司が雑用を部下に押し付けるような関係ではなく、顧客と開発者は対等な関係でなければならない。自分でやれることは自分でやる。協力すべきことは協力する。そういうマインドでなければチームは結束しない。顧客と開発者の間に線引きをするのは、壁を作り、コミュニケーションコストを増大させ、無用なリスクを呼び込むことにしかならない。