と考えてしまいがちです。私もかつてはそうでした。
図1 ドキュメントはシステムとは別物ドキュメントはシステムの本質的な構成要素
ところが実際にはアジャイル開発者はドキュメントを大切にします。これは私が周囲のアジャイル開発者との交流から学んだことの中でも二番目に重要なことです[3] 。
アジャイル関連の著作が多いScott Amblerも、『 オブジェクト開発の神髄』（ 注4 ）の中で「どんなシステムにもドキュメントは本質的な部分として含まれます。アジャイルソフトウェア開発手法で作られたシステムでも同じです」と宣言しています。つまり、アジャイル開発者のシステムとその構成要素に対する認識は図2 のようになっているのです。
図2 ドキュメントはシステムの本質的な構成要素ドキュメントとコードは同じぐらい大切
ちなみに図2では「ドキュメント」の四角が「プログラム」の四角に重なっていますが、これは作図ミスではありません。アジャイル開発者にとってドキュメントにはプログラムも含まれます 。これについては後述します。
アジャイル開発者にとってドキュメントはシステムの本質的な一部ですから、プログラムとして書くコードと同じように大切なものです。ということは、アジャイル開発者にとってドキュメントはコードと同じようにビジネス価値を提供しなければなりません。
ソフトウェアに対する要求を動作するソフトウェアとして 早めに実現し、こまめに提供し続けることがアジャイル開発の核心です。連載の第1回 （本誌Vol.39）で説明したように、ソフトウェアの価値は「価値の大きさ×価値を生み続けている時間」です。よって、システムのビジネス価値の提供に結びつかないドキュメントはムダであり、削減の対象となります。
アジャイル開発とドキュメント
しかし、ドキュメントのムダを省くといっても、やみくもにドキュメントの量を減らせばよいというものではありません。ここまでなんの断りもなくドキュメントという言葉を使ってきました。アジャイル開発者がドキュメントをどうとらえているかを大まかに分類すると次のようになります。
中間成果物としてのドキュメント
ソースコードとテストコード
利用者向けドキュメント
コンプライアンス目的のドキュメント
ロゼッタストーンドキュメント
それぞれについて、以下で順番に説明します。結論からいえば、アジャイル開発でムダとみなして削減するのは「中間成果物としてのドキュメント」だけです。
中間成果物としてのドキュメント
冒頭で紹介したアジャイルマニフェストの項目で「包括的なドキュメント」と呼ばれているものの多くがこれに該当します。中間成果物とは、要求定義→設計→実装→テストといったいわゆる「開発工程」の区切りに作成されるドキュメントのことです。仕様書や外部設計書、詳細設計書、テスト仕様書、テスト実施報告書などがその代表的です。
連載の第3回 （本誌Vol.41）で説明したとおり、アジャイル開発ではプロジェクトという仕組みで「ストーリとして記述されたユーザの要求をソフトウェアとして実現させて、ユーザからのフィードバックを得る」というループを効率よく回すことがカギです。ストーリ（＝ユーザの要求）から動作するソフトウェア（＝コード）までの過程は短いほうが望ましいのです。
そのため、アジャイルな開発では中間成果物のドキュメントを極力減らします。作成・維持コストもできるだけ低減させることを心がけます。
ソースコードやテストコード、自動化スクリプト、口頭やホワイトボードによる直接伝達、Wikiページや情報カードなどで代替できるものは、どんどん置き換えていきます。
中間成果物としてドキュメントが必要となる典型的なケースは、工程の区切りで担当者や組織が変わってしまうことです。これを極力減らすのが最も効果的です。もちろん、組織や発注の形態によってはこうしたドキュメントをなくせない場合もあります。その場合は量の削減を心がけます。
ソースコードとテストコード
ユーザの要求を実現させるにあたり、アジャイル開発者が中間成果物に代わって重視するのがソースコードとテストコードです。ここでよくある質問です。「 ソースコードやテストコードはプログラムでは？」――この答えは半分だけイエスです。
図2に示したようにプログラムは、とりわけソースコードとテストコードはアジャイル開発者にとって重要なドキュメントです 。「 なぜコードが重要なドキュメントなのかというと、詳細かつ正確なドキュメントはコードしかないから」（ 注5 ）です。
みなさんも経験があると思いますが、既存のコードを保守する際に、設計書とソースコードとで記述が異なっていた場合は、ソースコードを優先することが多いのではないでしょうか。潔く「コードはドキュメントである、それも最重要ドキュメントである」と認めたほうがプロジェクト全体の効率は高くなります。「 コードが最重要である」という点については「マインドセット」の項で説明します。
利用者向けドキュメント
操作マニュアルや、システムの概要を説明した利用者向けドキュメントは、典型的なシステムの構成要素となるドキュメントです。スムーズに使ってもらうためにも重要です。利用者向けドキュメントが、開発チームではないシステムのユーザがシステムを理解するための唯一の手掛りであることもあります。
積極的に開発に利用していくぐらいの心構えが必要です。たとえば、テスト駆動開発的に、マニュアルの記述をシステムに対する最も大きな粒度のテストケースとすることもできるでしょう。
コンプライアンス目的のドキュメント
自分の所属先やお客様が組織としてコンプライアンスのためにドキュメントを必要とすることがあります。CMMやISO 9000などの認証のため[6] や、調達部門の検収条件として必要なドキュメントは、ビジネスのために必要です。
であれば、これらのドキュメントもシステムの構成要素です。よって、プログラムと同様にあらかじめプロジェクトの計画づくりの対象になります。計画づくりのためには見積りも必要です。ドキュメントが必要十分となるレベルはどれぐらいなのかを事前に確認するのも大事な仕事です。
ロゼッタストーンドキュメント
ロゼッタストーンとは、ナポレオンのエジプト遠征時にロゼッタで発見された石碑で、同じ内容が3種類の文字で書かれていたことから、エジプト語の神聖文字を解読する突破口となりました（写真1 ） 。
写真1 ロゼッタストーンロゼッタストーンという言葉は、難問や、難問を解読したり翻訳したりすること表すたとえとしても使われます。ロゼッタストーンドキュメントが解読を助けようとする「難問」は、開発対象システムに対する理解です。
ロゼッタストーンドキュメントには、ソースコードやテストコードだけでは理解しづらい、開発対象システムの全体像の把握につながるヒントを記します。もう少し具体的な説明は「プラクティス」の項で行います。
アジャイル開発者に限った話ではない
結局、アジャイル開発で削減対象となるドキュメントは「中間成果物としてのドキュメント」だけです。前述のアジャイルマニフェストで「動作するソフトウェア」の比較対象としているのは「包括的なドキュメント」であって、「 あらゆるドキュメント」ではありません。
ドキュメントに向き合う姿勢は、アジャイル開発者に限った話ではありません。ここで簡単にまとめておきます。
明確でわかりやすい文章を書く
明確でわかりやすい文章を書くことはすべての開発者にとって重要なスキルです。自分のことを棚に上げて言えば、私の周囲にも、きちんとしたコードを書けて、議論もしっかり論理的にできるのに、ドキュメントを書くのはそれほどでもない開発者が少なからずいます。
ですが、文章の書き方については連載の範囲から逸れ過ぎてしまうので、ここでは参考になる書名だけを挙げておきます。
まず、文章の書き方の基礎として『理科系の作文技術』（ 注7 ）と『日本語の作文技術』（ 注8 ）を推薦します。それから、技術ドキュメントを書くうえでのチェックリストとしても有効なのが『わかりやすいマニュアルを作る文章・用字用語ハンドブック』（ 注9 ）です。業務マニュアルの書籍ですが『いきいき社内マニュアルの作り方』（ 注10 ）は、そのまま実践するかはさておき「マニュアル」に対する考え方を深めるうえで参考になります。
文章の上達はプログラミングと同じように「読んで読んで読み、書いて書いて書く――そしてレビューしてもらってフィードバックを得る」のが一番です。
ドキュメントはコミュニケーションメディア
これもあらゆるドキュメントに当てはまることですが、基本的にドキュメントは読み手に伝えるために書く、コミュニケーションのためのメディアです。ですから「ドキュメント」といっても必ずしもWordやExcelで作成する必要はありません。
情報を伝える手段はさまざまです。口頭の会話による伝達は、アジャイル開発者が最も重視するコミュニケーション手段です。また、ホワイトボードでの議論の結果やソースコード、テストコードも情報を伝えるための立派な手段です。形式にとらわれずに「情報を伝える」という目的を達成する最適な手段を選ぶことが重要です。
もちろん伝える相手によっては、WordやExcel、あるいはPowerPointのスライドが適切な場合もあります。
ドキュメントの利益とコスト、そしてリスク
ドキュメントそのものをなくしたり、量を減らせばコストを下げられます。ここでのコストには、最初の作成コストだけでなく、最新の情報にアップデートしていくための保守コストも含まれます。
いつまでも情報が古いままのドキュメントは価値がないどころか害をなすこともあります。保守するドキュメントの量は少ないほうがよいでしょう。ただし、ドキュメントをシンプルにするためには思った以上に、シンプルにする作戦を考える時間が必要です。記述量を減らせば単純にコストが減るというものでもありません。
また、ドキュメントを減らすと、書いていないことが読み手に伝わらないリスクが増えます。「 口頭の伝達ですむから」とドキュメントにしなければ、一見コストは削減できます。しかし、問い合わせがあるたびに対応が必要になります。
この場合はフィードバックをもとにドキュメント化するかどうかを決めるのもよいでしょう。たとえば「3回問い合わせられたらドキュメント化する」といったようにです。
つまり、ドキュメントに投入するコストを減らせば、それだけ伝達ミスのリスクが増えます。かといってリスクをゼロにしようとするとドキュメント作業の工数が増大します。どこでバランスを取るかは、組織やプロジェクトの状況によりけりです。
ドキュメントの特性や、それを減らすための作戦については、『 ドキュメントハックス』（ 注11 ）が手軽にまとまっていて参考になります。
習慣 #3 ドキュメントを大切にする
では、連載の主旨に従って、ここではアジャイル開発の現場でのドキュメントに対する心構え（マインドセット）と実践（プラクティス）を紹介します。改めて考えてみると、アジャイル開発の現場ではドキュメント作成のプラクティスがいくつも行われています。2つしか紹介できないのは残念です。
マインドセット「コードは最重要ドキュメント」
「 アジャイル開発とドキュメント」で述べたとおり、アジャイル開発者にとって「コードは最重要ドキュメント」です。
ソースコードは設計である
ソースコードが最重要ドキュメントなのは、ソースコードは設計だからです。そして設計はテストによって検証されねばなりません。 いわゆる「製造」はコンパイラやリンカ、ビルドツールの仕事です。この考えを理解するためには、Jack W. Reevesによる「ソフトウェア設計とは何か？ 」という15年前に書かれた素晴らしい論文をぜひ読んでください。何度も読み返す価値のある論文です。
テストコードは実行可能なサンプルコード
テストコードはソースコードと対になる、不可欠な存在です。テストコードは設計（＝ソースコード）が期待どおりに動作することを検証します。設計はテストによって検証されて初めて完了します。ですからソースコードも最重要ドキュメントです。
また、テストコードは実行可能なサンプルコードとしても利用できます。といっても、テストコードが表現するものはあくまでも「具体的にこうすればこう動く」というものであって「仕様そのもの」ではありません。場合によっては仕様を説明する補助ドキュメントを用意したほうが効率よく情報を伝達できることもあります。
しかし、テストコードがコードの挙動を端的に示すドキュメントであるという考えは、もっと認知されてよいと私は考えますし、実際アジャイル開発者の多くはそう考えています[12] 。
ドキュメントのようなコード
詳細なプログラム設計書やテスト設計書がソースコードやテストコードと情報が重複していくのは、ある意味当然といえます。コードはドキュメントなのですから。重複は「繰り返しをなくす」というDRY（Donﾕt Repeat Yourself）原則違反でもあります。
とはいえ、ここで一つ注意を。冒頭に引用した某Ruby設計者のように「ソースコードがドキュメントだ」とうそぶくのは簡単です[13] 。しかし、ドキュメントのようなソースコードを書くには技術が必要です。
コードがドキュメントとして役に立たないのは、プログラマがコードのことを真剣にドキュメントとして扱っていないからです。スタイルを統一すること、クラスやメソッドに適切な責務を割り当て、よい名前を選ぶこと、意図を明確に表現する単位でメソッドを記述すること……まだまだ続きます。プログラムを書く際に「このコードはドキュメントとして通用するか？」を自問することは重要です。
意図を明確に表現するコード
誌面も限られているので、意図を明確にするコードの簡単な例を1つだけ挙げます。Erich GammaとXP（エクストリームプログラミング）の提唱者であるKent Beckは『Eclipseプラグイン開発』（ 注14 ）の中で、プロジェクト中のクラスからJUnitで実行対象とするすべてのテストケースを見つけ出すためfindAllメソッドを次のように書いています。
public IType[] findAll(IJavaProject project,
IProgressMonitor pm)
throws JavaModelException {
IType[] candidates =
getAllTestCaseSubclasses(project, pm);
return collectTestInProject(candidates, project);
}
findAllでは、引数として渡されたprojectからTestCaseのサブクラスをすべて取得して、それを抽出候補（candidates）とし、さらにプロジェクトに関連するものだけを集めている――このことを、関連するメソッドの詳細を読まなくても理解できます。
また、「 XPの父」（ 注15 ）の一人であるRon Jefferiesは、以前Rubyのメーリングリストに投稿したメール で「メソッドが12行なんて長過ぎる。1、2行でよい」と主張していました。紹介だけになりますが、興味深いです。
この話題については、Kent Beckの『Implementation Patterns』（ 注16 ）や『ケント・ベックのSmalltalkベストプラクティス・パターン』（ 注17 ）といった書籍が非常に参考になります。書籍でのコード例はJavaやSmalltalkですが、その考え方は言語を問わず有効です。
マインドセット「「なぜ」をドキュメントに残す」
いくら「コードがドキュメントだ」といってもそこには限界があります。というのも、ソースコードやテストコードでは「What（何を） 」や「How（どうやって） 」を表現することはできますが、「 Why（なぜ） 」 「 Why not（なぜXXでないのか） 」は書けません。判断した結果をコードで表現しているのですから、当然です。 コードのWhy、Why notは、ロゼッタストーンドキュメントやソースコードのコメント、バージョン管理のコミットログに書かれるべきです。
『達人プログラマー』（ 注18 ）でも、バージョン管理へのコミットログもドキュメントであり、そこにはコミットログでしか書けないこと、つまり「なぜこの変更をしたのか」を書くべきだというコラムがあります。誰が、何を、いつ、どうやって変更したかはツールから情報を得られますが、「 なぜ変更したのか」は、人間の手で書くしかないのです。
「なぜ」「 なぜXXでないのか」を書くことはコード以外のドキュメントでも重要です。直接話のできないドキュメントの読み手に意図を伝えることができるからです。
プラクティス「ホワイトボード」
私の周囲のアジャイル開発者たちは、とにかくホワイトボード好きが多いです。さまざまな議論がホワイトボードに向かって行われます。ホワイトボードの議論の結果は、デジタルカメラでスナップショット画像として撮影し、保存します。この画像をミーティングの議事録や設計ドキュメント（の一部）とすることもあります。
ほとんど同じことはクリップボードに挟んだ裏紙を使っても可能なのですが、ホワイトボードのほうが断然人気です（写真2 ） 。私の周囲にはA4サイズのホワイトボードを購入したり自作して持ち歩いている強者もいます。
写真2 私の職場には大量のホワイトボードが配備されていますアジャイル開発者たちがホワイトボードを好むのは、記述と修正の手軽さはもちろんですが、ホワイトボードには問題を解決する「場」としての効果があるからだと私は考えています。
ソフトウェアを開発するのは問題を解決するためです。問題解決に向けて議論をする際には、ホワイトボードに問題を書き出し、参加者がそこに向き合うことで、「 あなた VS. 私」という不毛な構図ではなく「問題 VS. 私たち」という構図を物理的に演出するのです。
プラクティス「Wiki」
いつでも誰でもWebページをブラウザから編集できるWikiは、情報共有が重要なソフトウェア開発プロジェクトと相性がよく、アジャイル開発に限らずよく利用されています。
プロジェクトで作成するありとあらゆるドキュメントがWikiで共有する対象となりえます。ミーティングの議事録やストーリ、受け入れテストの記述、ソースコードのビルド手順、設計判断の結果や仕様、アプリケーションサーバの落とし穴、有用なTips、チームメンバーの日報、後述するロゼッタストーンドキュメントなどなど……。
利用するWikiの実装としては、私はTrac とHiki とqwik を用途に応じて使い分けています。また最近はRetrospectiva に注目して実験的に導入しています。
私の経験ではアジャイルなプロジェクトではWikiが有効に活用されていることが多く、個人的に「Wikiが育つところはアジャイルになれる」という仮説を立てています（コラムも参照してください） 。
プラクティス「ロゼッタストーンドキュメント」
ロゼッタストーンドキュメントは（自分自身も含めた）未来のチームメンバーに向けて書く簡潔な手引書です[19] 。ロゼッタストーンドキュメントには必ず次の2点を含めます。
ビルドとテストの実行手順
システムを理解するとっかかりとなる文章やダイアグラム
適切なテストコードを用意しておけば、実際に動かせるサンプルとして利用してもらえます。理解のとっかかりとなる文章やダイアグラムには、システムの狙いと概要、設計の根拠、抽象度の高いクラス図や主要なシーケンス図を含めます。
「設計文書のうまい書き方 」や「Project Aardvark機能仕様書 」といったオンライン記事は、ロゼッタストーンドキュメントそのものではありませんが、簡潔な設計ドキュメントを学ぶ起点になります。参考にしてください。
今回のまとめ
今回は少し目先を変えて、アジャイル開発者にとってのドキュメントに対する考え方を紹介しました。誌面の都合上、ごく表面的にしか言及できなかったことが残念ですが、「 アジャイル開発はドキュメントを書かない」という根深い誤解を解くきっかけになれば幸いです。アジャイル開発ではむしろ「なにもかもがドキュメント」なのです。それでは、また次回お目にかかりましょう。acts_as_agile!
