特集：ツールを使ったドキュメント作成技法（前編） 価値のある開発ドキュメントを効率的に作成するには？ アバナード株式会社　市川 龍太（Microsoft MVP 2008 for XML） 2008/05/20
Page1 Page2 Page3

■価値のあるドキュメントを作成するコツ

　ここからは価値のあるドキュメントを書くためのコツについて、いくつか紹介していく。

●ドキュメントを書く目的を意識する

　ドキュメントを書く前に、そのドキュメントを書く目的を意識することは非常に重要である。つまりドキュメントを書く本当の目的が明確であれば、おのずと何を、どのように書けばよいのかが決まってくるのである。

　例えば詳細設計書を作成する目的として、以下のような状況が想定され得る。

• 詳細設計書を基に実際の開発を行う
• 納品成果物に含まれているために必要（実際の開発ではそれほど参照されない）
• 運用・保守向けに必要

　このうち、「詳細設計書を基に実際の開発を行う」のであれば、その設計書の内容は詳細かつ明解である必要があるが、「納品成果物に含まれているために必要」であるなら、見た目の体裁により気を使う必要が出てくるだろう。そして「運用・保守向けに必要」であるなら、実際の処理の内容を詳細に記述することよりも、なぜそのような設計になっているのかという点を意識して記述した方がよい。これは実際の保守開発においては、内部設計書を細かく読むよりも、ソース・コードを読むことの方が多いため、ソース・コードを読むに当たっての手引きとなるようなドキュメントが望ましいのである。

　つまり、ドキュメントを書き始める前に、「なぜそのドキュメントが必要であるのか」という目的をドキュメントの要求者に尋ねることが重要なのである。

●読み手を意識する

　これはドキュメントを作成する目的を意識すればおのずと考えが及ぶことではあるが、「これから作成するドキュメントは誰が読むのか？」ということを意識することが重要である。

　例えば技術知識にあまり精通していない顧客向けであれば、難解な技術用語は避けるべきだし、同じチーム内のエンジニア向けであれば多少掘り下げて書いても問題はない。運用担当者向けの場合は、開発者と運用者が異なる場合などを考慮して、チーム内であれば暗黙知として理解されていることでも詳細に記述しておく必要がある。

　それから読み手の立場に立って文章を書くこともまた重要である。決してドキュメント作成者の主観だけで、これは分かっているだろうから書く必要はないと思い込むことは危険である。読み手がそのドキュメントからどういった情報を読み取る気でいるのかを意識し、それに合わせて書く必要がある。

●ドキュメントの構成をイメージする

　ドキュメントを書く際に、ただ漠然と書き始めるのではなく、全体の構成をイメージしてから書き始めると、頭の整理がしやすくなる。前述した目的と読み手があやふやな状態で、さらにドキュメントの構成もイメージせずに書き始めると、まったくもって支離滅裂な内容のドキュメントが作成されてしまう。

　ドキュメントを書く前に、せめて大見出しだけでも構成案を決めておき、それから書いていくというアプローチを採るだけでも随分と頭の整理ができ、結果、読みやすいドキュメントを効率的に作成できるだろう。

●ドキュメント間で整合性が取れている必要がある

　ウォーターフォール型開発のように各工程が明確に分かれ、順番に工程を進めていくような開発スタイルの場合は、前工程で作成されたドキュメントが、後工程におけるドキュメント作成においてのインプットとなる場合が多い。

　例を挙げれば、「要件定義書」→「基本設計書」→「詳細設計書」という形で、要件定義書は基本設計書のインプットとなり、基本設計書は詳細設計書のインプットとなる。これによって、その内容がより詳細化・具体化されていくわけだ。

　この場合、よく生じる問題が、関連する上位または下位のドキュメントが分からず、多くの時間をドキュメントの検索に割いてしまうという問題である。この問題を解決するには、各ドキュメントに一意なIDを振り、関連するドキュメントのIDを各ドキュメントに明記するなどの対応を取るのが一般的であるが、本稿（後編）ではpatters & practices Documentation Toolsを使った方法について解説する予定である。

　以上のような「ドキュメントを作成するためのコツ」を意識することが、無駄がなく目的がはっきりとした価値のあるドキュメントを作成するための近道になるだろう。

［参考］発注者ビュー検討会

「発注者ビュー検討会」というのをご存じだろうか？ 発注者ビュー検討会 　発注者ビュー検討会とは、開発者だけでなく、顧客（つまり発注者）にとっても分かりやすい記述方法および合意方法を模索するために、国内の主要SI事業者が結集した検討会のことである。現在は外部設計フェイズに焦点を絞った以下のガイドラインが公開されている。 画面編 システム振る舞い編 データモデル編 　各ガイドラインは、100ページを超えるボリュームであるが、対応する各ドキュメントを作成するに当たってのポイントが丁寧に解説されているため、大いに参考になるだろう。

■ツールを使ったドキュメントの作成技法

　ドキュメントをアジャイルに作成するには、ツールの活用も欠かせない。ツールによるドキュメント作成では、クラス仕様書（いわゆるAPIリファレンス）の自動生成が最もよく実践されている。以前のVisual Studio .NETでは、“NDoc”というツールが使われていたが（参考「.NET TIPS：C#でMSDNライブラリ風のAPIリファレンスを作成するには？」）、Visual Studio 2005以降ではマイクロソフトが提供する“Sandcastle”というツールを使用するのが一般的だ。

　そこでここからは、ツールによるドキュメント作成の一例として、Sandcastleを使った効率的なAPIリファレンスの作成技法について解説する（後編では、このほかのドキュメント作成ツールについても紹介する）。

　Sandcastleとは、ソース・コード上に記述されているXMLドキュメント・コメント（詳細後述）からCHM（コンパイル済みヘルプ）形式ファイルやHTML形式ファイルを自動生成してくれるツールだ。これは、Codeplex（ソフトウェアの共同開発を支援するためのポータル・サイト）内の以下のサイトから入手可能である。

• Sandcastle入手先

　今回はSandcastleの支援ツールである「Sandcastle Help File Builder」も使用するため、これについても以下のサイトから入手しておく。

• Sandcastle Help File Builder入手先

　両ツールともにmsi（Windowsインストーラ）形式ファイルであるため、そのままファイルをダブルクリックすればインストールできる。

　それでは以下では、Sandcastleを使用してCHM形式ファイルを生成する手順について解説していくことにする。

INDEX
	[特集]
	ツールを使ったドキュメント作成技法（前編）
	価値のある開発ドキュメントを効率的に作成するには？
	1. アジャイル・ドキュメントとは何か？
	2. 価値のあるドキュメントを作成するコツ
	3. ツールを使ったドキュメントの作成技法
	ツールを使ったドキュメント作成技法（後編）
	マイクロソフトも実施しているドキュメント作成技法
	1. 柔軟なXMLドキュメント・コメントを生成する「GhostDoc」
	2. GhostDocとSandCastleを組み合わせたドキュメント作成技法
	3. マイクロソフトも活用する「patterns & practices Documentation Tools」

＠ITメールマガジン　新着情報やスタッフのコラムがメールで届きます（無料）