特集：ツールを使ったドキュメント作成技法（後編） マイクロソフトも実施しているドキュメント作成技法 アバナード株式会社　市川 龍太（Microsoft MVP 2008 for XML） 2008/07/23
Page1 Page2 Page3

■マイクロソフトも活用する「patterns & practices Documentation Tools」

　Documentation Toolsは、マイクロソフトの中で各種ガイドラインやベスト・プラクティスを公開しているpatterns & practicesチームにおいて日常的に使われているツールであり、同チームの成果物であるEnterprise Libraryや各Software Factory（Smart Client Software Factory、Web Client Software Factory、Web Service Software Factoryなど）のドキュメント作成においても日常的に使用されているツールなのである。

　このDocumentation Toolsは、最終的にCHM形式ファイルを生成するという点ではSandCastleと同じであるが、SandCastleはVisual Studioから出力されるアセンブリ・ファイルとXMLドキュメント・ファイルからCHM形式ファイルを生成するのに対して、Documentation Toolsは、Word 2007形式ファイル（.docxファイル）から生成する点が異なっている。

　Documentation Toolsの使い方について解説していこう。Documentation Toolsは以下のツールによって構成されており、それぞれ個別にダウンロードする必要がある。

ツール名	機能説明	ファイル名
ppContent	Word 2007テンプレートとWord 2007用アドイン	ppContentSetup.msi
MasterTocTool	Word 2007形式ファイルの構成設定エディタ	MasterTocTool.msi
DocxConverterTool	Word 2007形式ファイルと構成ファイルからCHM形式ファイルを生成するPowerShellスクリプト	DocxConverterTool.msi
Documentation Toolsを構成するツール一覧

　Word 2007形式ファイルからCHM形式ファイルを生成するには、以下の順番に従ってこれらのツールを使用する必要がある。

1. ppContentのテンプレートとアドインを使用して、Word 2007形式ファイルを作成
2. MasterTocToolを使用して構成ファイルを生成
3. DocxConverterToolのPowerShellスクリプトを使用してCHM形式ファイルを生成

　以降ではこれらのツールの使い方を順番に解説していくわけだが、Documentation Toolsを動作させるには、以下の環境が必要であるため、まずは以下のコンポーネントをインストールしておく必要がある。

• Microsoft Office 2007
• .NET Framework 2.0
• .NET Framework 3.5
• 2007 Microsoft Office System Update: Redistributable Primary Interop Assemblies
• Microsoft Visual Studio Tools for the Microsoft Office system （Version 3.0 Runtime）（x86）
• HTML Help Workshop

　ここで1つ注意点がある。Documentation Toolsは現在CTP（Community Technical Preview）版であるため、日本語版のOffice 2007ではうまく動作しない。そのため本稿では英語版のOffice 2007を使用する（この環境でも日本語のドキュメントは作成可能である）。

　続いて各ツールをCodeplex（ソフトウェアの共同開発を支援するためのポータルサイト）上の以下のサイトから入手し、インストールする。

• ppContent入手先
• MasterTocTool入手先
• DocxConverterTool入手先

●ppContentを使用してWord 2007形式ファイルを作成

　ppContentのインストール後にWord 2007を起動すると、次の画面のように、リボンに新しく［p&p Content］タブが追加されている。

リボンに新しく追加された［p&p Content］タブ

　［p&p Content］タブには、主にppContent用のスタイル設定が用意されているのだが、デフォルトではほとんどのボタンが無効になっており、［Attach Template］ボタンをクリックして初めて有効になる。

　それではサンプルとして新しく文書を作成してみる。まず左上のOfficeボタンから［New］を選択して［New Document］ダイアログを表示する。このダイアログ上の［Templates］リストから［My Templates］を選択すると表示される［My Templates］ダイアログには、ppContent用のテンプレートである「ppContent.dotx」が新しく追加されている。

新しく追加された「ppContent.dotx」テンプレート

　最後にこの「ppContent.dotx」テンプレートを選択し、［OK］ボタンを押下すると新規文書が作成される。

　以下に新規作成されたファイルに任意の内容を記述したドキュメントのイメージを示す。テンプレートで用意されたスタイルを使用しながら、大見出しや小見出しを付けていく。

「ppContent.dotx」テンプレートから新規に作成された文書

「ppContent.dotx」テンプレートで生成した文書に任意の内容を書き加えたところ。

ppContent.dotx用のカスタム書式が使える。

　なお、文書の中には必ずTopic行が存在する必要がある。Topic行を作成するには、任意の行（サンプルでは「patterns & practices Documentation Tools」「GhostDoc」「SandCastle」）に入力カーソルを置いて、［p&p Content］タブにある［Topic］ボタンをクリックするだけでよい。

　最終的にCHM形式ファイルにコンパイル（詳細は後述する）される際に、このTopic行単位でページが作成されるため、文書内にTopic行が存在しないとCHM形式ファイルの生成時にコンパイル・エラーになるので注意が必要である。文書の作成が完了したら任意の名前（ここでは「DocToolSample.docx」）で保存する。

●MasterTocToolを使用して構成ファイルを作成

　MasterTocToolを起動しWord 2007形式ファイルを読み込むと、文書作成時にTopicとして設定した行が右ペインに表示される。

MasterTocToolの画面

MasterTocToolを起動してWord 2007形式ファイルを読み込んだところ。

Word 2007形式ファイルを読み込ませる場合は、［＋］ボタンを押下する。

　複数の文書をマージして、1つのCHM形式ファイルを作成する場合は、マージ対象のWord 2007形式ファイルを連続して読み込ませるとよい。設定が完了したら、任意の名前で保存するとXML形式の構成ファイルが生成される（ここでは「DocToolSample.xml」）。

●DocxConverterToolsを使用してCHM形式ファイルを作成

　ここまででWord 2007形式ファイル（DocToolSample.docx）と構成ファイル（DocToolSample.xml）がそろったら、いよいよCHM形式ファイルの生成に入る。まずコマンド・プロンプトを起動し、以下のPowerShellコマンドを実行する。

PowerShell ConvertToCHMFromMasterToc.ps1 DocToolSample.xml <ファイル出力先パス>

　無事に実行が完了すると、出力先パスにCHM形式ファイル（デフォルトではProjectName.chm）が生成されているはずである。なお、ConvertToCHMFromMasterToc.ps1は、DocxConverterToolが提供するPowerShellスクリプトであり、自動的にインストールされる。最後に生成されたファイルのイメージを以下に示す。

生成されたCHM形式ファイルの例

DocxConverterToolを使って生成したCHM形式ファイルを表示したところ。

Topic単位でページが作成される。

　ここまでDocumentation Toolsの使い方について解説してきたわけだが、それでは実際にDocumentation Toolsをどのようなシチュエーションで使用すればよいのだろうか？

　まず1つ挙げられるのはマニュアル作成であろう。それなりの規模のシステムでは、複数のサブシステムによって構成されていることが多く、これらサブシステムごとにチームが分かれる場合が多い。この際、個々のチームがバラバラにマニュアルを作ったのでは、統一感がなくて読みづらく、相互にマニュアルを参照しなければならない場合などに不便である。そこでDocumentation Toolsを使って個々のマニュアルを1つにまとめれば、マニュアルを相互に参照する場合でも簡単に行えるだろう。

　ほかにも前編において、「ドキュメント間で整合性が取れている必要がある」と書いたが、これについてもppContentのスタイルで要件定義書、外部設計書、内部設計書の各ドキュメントを記述し、MasterTocToolで関連のある各ドキュメントを1つのファイルにまとめてしまえば、上位および下位のドキュメントを参照しやすくなる。

　この場合、ドキュメントに変更が入るたびにファイルを作り直すのが面倒に思われるかもしれないが、前述したPowerShellを使用したスクリプトの実行を自動化しておけば、それほど大した手間にはならないだろう。

■

　これまで前・後編にわたってツールを使ったドキュメント作成技法について解説してきたわけだが、確かにこれらのツールを使うことで、より効率的にドキュメントを作成することが可能になる。

　ただし、ドキュメントが十分かどうかを決めるのは、顧客であって開発者ではない。そのため、時には多くの工数を割いて膨大なドキュメントを作成しなければならない場合もあるだろう。そのような場合、ツールを使ってドキュメント作成工数をなるべく減らすことをまず考えるよりも、なぜそのドキュメントが必要であるかを、顧客と開発者間でしっかりと話し合うことこそが最も大事であるということを忘れてはならない。

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

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