ほとんどの開発プロジェクトでは、「ドキュメントが整備されていない」という問題が起きているかと思います。どうしたらドキュメントを満足いくレベルに書き上げることができるでしょう。今回は常にドキュメントを最新に保てる管理方法についてお伝えします。

はじめに

アジャイル宣言には、「包括的なドキュメントより動くソフトウエアを」という言葉があります。これはドキュメントを作成することに注力しすばらしいドキュメントを作成したのにシステムは動かない、という事例への反省から出た概念と思います。最近では誤解も解けたかと感じますが、以前はこの宣言から、「アジャイル開発ではドキュメントは書かないんでしょ」という意見も聞こえていました。もちろんごく一部の例外を除いては、システム開発にはドキュメントは必要、に異論は無いと思います。ただどのようにドキュメントを書いていくかについては触れられてきませんでした。

ドキュメントとは

そもそもシステム開発になぜドキュメントが必要なんでしょうか。それは、「何を作るか明確にしないと作るものがわからないから」です。

これは一つのチームでコミュニケーションを密にしていけば無理にドキュメンテーションをしなくても実際に動くシステムは作ることができるはずです。また、簡単なメモ、ホワイトボードの写真、付箋などで十分な場合も多いはずです。しかし大事なのは作ることはできても維持していくことはできないということです。ドキュメントを書くのは作る際に何をどう作るかということよりもより以下の点の方が重要ではないでしょうか。

  • この機能はもともと何を目的としているか
  • この機能はどのような条件の時にどのように振る舞うのか
  • 振る舞った結果、どのような影響をどこに与えるのか
  • 機能に漏れや齟齬は無いか

これらの内容は実際に動かしてみればわかる、という人もいるでしょうが、特定の条件を作ることが難しい場合があります。たとえば、2月29日にはどのように振る舞うのか確認する際には、実際にシステム日付を2月29日に変更しなければ動作は確認できません。さらに影響範囲となると動かした後の確認も多岐にわたりさらに条件も加わるので簡単には確認できない場合も多いでしょう。そのような部分をドキュメント化しておくことが重要だ、という点には異論のある方は多くないと思います。

ドキュメントを書く労力

ではドキュメントが重要だからやっぱりコーディングする前に完璧なドキュメントを書くべきなんでしょうか?

いいえ、自分がリーダー務める現場ではドキュメントの完成は目指しません。コーディングと設計書は常に並行して作業を進めています。というのも、どういう条件の時にどういう振る舞いをするかなどは、想像だけで書くより実際にコーディングしながら書いていく方が、はるかに早く確実に正確な内容を記述することができるからです。

ただ開発現場にいれば皆経験していると思いますが、どんなに完璧なドキュメントを書いたと思っても開発後半には必ずドキュメントの不備が見つかるものです。そう、大抵の場合はシステムが完成する前には完璧なドキュメントを書くことはできないのです。完璧に書くことができないのなら、最初から諦め簡単な記述だけしておき、開発中に不備が見つかったらその場で即時に修正していけば効率が良いと思いませんか? 自分はこのスタイルを数多くのプロジェクトで実施してきました。そのおかけで少ないドキュメント作成の工数で充実したドキュメントを残せてきました。実際の開発現場ではよく行われていると思いますが、従来は「良くないやり方」とされてきました。きちんとした設計ができていなければきちんとした実装ができない、という価値観ですね。しかし完璧なドキュメントは書くことができず、開発時に不備や漏れが発覚するたびに工程を戻るなど、現実ではほとんどのプロジェクトでは実施していないと思います。問題なのは、ドキュメントは完成しているとしているので、そこで修正を加えずそのまま先に進んでしまうことが多々発生している点です。

ドキュメントは完成しない

他のプロジェクトの状況を見ていて最も間違えていると思うことは、「ドキュメント作成が終了しました」という報告がある点です。ハッキリ言いましょう。ドキュメント作成は終了しません。それは納品後ですら終了とは言えないはずです。そもそもドキュメントは人間がシステムを表現する手法で、書くのも人間なら読むのも人間です。読んで解釈している人間が一人ではないのですから誰にでもわかるドキュメントなんてあるわけが無いのです。またバグが出ればドキュメントの修正が必要なケースも多いはずですし、要件だって変更になることはあります。その際にドキュメントの修正を忘れるのは「ドキュメント作成が終了」していると思っているからです。システムが生きていて、解釈する人間が複数いる以上、ドキュメントも常に変更されていかなければいけないのです。

自分のチームではドキュメントを読む人は全員ドキュメントを書く人でもあります。わかりにくいと思ったら、その人がその時点で加筆修正しますし、コード修正する際にも都度ドキュメントを修正しなければいけないので、そのため自分のチームではプログラム専門家や設計専門家というのをなるべく置かないようにしています。設計者でもコーディングするし、コーディングする人も設計書を修正する、というのが基本です。そのような体制にしないと確実にドキュメントは古くなりシステムと同期が取れなくなるからです。

そして設計しながらコーディングし、コーディングしながら設計書も書くためには素早く目的の文書を見つけ、即時に書き込めなければなりません。そのためにはExcelやWordで文書を管理していては文書を探して修正箇所を見つけるだけでも時間がかかり、そのスピードについていけません。また開発者全員がそれぞれがそれぞれ並列にドキュメントを加筆修正していくことになり、ExcelやWordでは文書の競合が多く発生してしまいます。そのため自分のチームではドキュメントはすべてWikiで管理しています。そのおかげで常に最新のドキュメントを維持管理できています。

納品物

「そんなこと言ったって、納品物件はExcelで記載すること。規定フォーマットを使用すること、と書いてあるんです」という人もいるでしょう。ドキュメントに形式を求めること自体ナンセンスです。形式を求めるのは記載の漏れを防ぐ意味では効果的かもしれませんがあまりそれ以外のメリットがありません。どうしても規定フォーマットが必要ならWikiにテンプレートなどを登録して利用すれば良いでしょう。

納品物の形式やフォーマットに規定がある場合は、「本当に必要なドキュメントを少ないコストで維持しませんか?」とお客様に提案してください。自分の経験ではWikiのまま(もしくはWikiをPDF化)で納品できたケースは全体で80%程度はあります。「納品物は社内規定があるからWikiはNG」というケースもありますが、その場合は納品時にWikiからWordやExcelに転記して納品しています。納品時にドキュメントをコピーするムダが発生するのですが、そのムダを差し引いても上記メリットがあるため、必ずWikiを利用しています。

まとめ

アジャイル開発現場ではドキュメント作成に時間や労力をかけません。動くソフトウエアを重視します。しかし、ドキュメント作成に時間や労力をかけなくても最適なドキュメントを維持していくことはできます。完璧なドキュメント作成を求めるのではなく、自分たちが最適と思える文書を変化させながら残し続けていくことが重要なのです。問題点に気づいたら気づいた人が即座に修正していく、これをチームの習慣とすれば、かなり品質の高いドキュメントを維持し続けることができます。ぜひみなさんもWikiを使ってドキュメント管理をしてみてはいかがでしょうか。

次回はイテレーション開発のノウハウをお伝えする予定です。

執筆者紹介

川上文夫

パッケージベンダーのグループマネージャーとして複数プロジェクトのPM、PLを兼務。要件定義からプログラミング、テスト、運用を担当している。数多くのプロジェクトのリーダーとして20年のキャリアがあり、オフショア開発の経験も豊富。独自プラクティスに軽量議事録、朝会Wiki、設計実装並列手法などがある。アジャイル系コミュニティにも所属し、記事の執筆やワークショップ登壇など精力的に活動を続けている。