ソフトウェアの取扱説明書(ガイダンス)を生成するツール

.Net Code Plex 



We are pleased to announce the availability of the patterns & practices Documentation Tools. These are the tools that have been used to create the accompanying documentation for many p&p projects, including the Enterprise Library, Smart Client Software Factory, Web Client Software Factory, and Web Service Software Factory. The tools allow authors to create guidance using Word 2007 and produce documentation in HTML, Help 1.0 (CHM), or Help 2.0 (HxS) format.

我々はこのたびpatterns & practices Documentation Toolsをリリースすることができてとても光栄です。このツールはp&pの多くのプロジェクトでドキュメントを作成するのに使われています。(Enterprise Library, Smart Client Software Factory, Web Client Software Factory, and Web Service Software Factoryなど)。
ガイダンスの作成者はWord2007でドキュメントの編集をおこない、このツールによってHTML,CHM,HxSのフォーマットのドキュメントを生成することが可能です。


なんというか、よくわからないのでとりあえず使ってみる。

ツールは、
・Word編集用のVSTOプラグインとテンプレート
・複数のドキュメントをまとめて目次を作成するツール
・変換ツール
の3部構成になっているらしい。


まずは、必要条件となっているソフトをインストールする



Microsoft Word 2007

Microsoft .NET Framework 2.0: http://www.microsoft.com/downloads/details.aspxFamilyID=0856EACB-4362-4B0D-8EDD-AAB15C5E04F5&displaylang=enMicrosoft 

.NET Framework 3.5: http://www.microsoft.com/downloads/details.aspx?FamilyId=333325FD-AE52-4E35-B531-508D977D32A6&displaylang=en2007 Microsoft Office system Primary Interop Assemblies. http://www.microsoft.com/downloads/details.aspx?familyid=59daebaa-bed4-4282-a28c-b864d8bfa513&displaylang=enMicrosoft Visual Studio Tools for the Microsoft Office system version 3.0 Runtime.http://www.microsoft.com/downloads/details.aspx?FamilyId=54EB3A5A-0E52-40F9-A2D1-EECD7A092DCB&displaylang=en
そのあとに、
http://www.codeplex.com/doctools/Release/ProjectReleases.aspx?ReleaseId=9951
ここにある、ppContentSetup.msiをダウンロードしてインストールする。


その後、Word2007を起動すると「Microsoft Officeカスタマイズインストーラ」に「ppContent」をインストールしますか？
と聞かれるので、「インストール」を選択する。


すると、p&pContentというリボンが追加される。
ここで、AttachTemplateをクリックすると、p&pContentの機能が有効になるはず。
(通常の書式設定ではなく、p&p Contentの書式設定を利用することによってMSDN形式のドキュメントに変更可能となるようだ。)


だが、ならない。


http://www.codeplex.com/doctools/WorkItem/View.aspx?WorkItemId=1948



Ribbon Bar Buttons are not enabled when the Attach Template Button is pressed if the Word 2007 Display Language is other than English!

Word2007の表示言語が英語以外の場合、Attach Templateボタンを押してもリボンバーのボタンが有効にならない。


なんですと！！
これだから、英語至上主義者は。Voteするためだけにメンバー登録してしまいました。


気を取り直して、表示言語を英語にしてっと。。。
を、家のPCはMultilingualバージョンじゃないので、表示言語が選べない orz


ひどいよ、ひどすぎるよー
明日会社のPCで試してみるよー


さて、もう一度気を取り直してこのツールがSIの現場でどのように生かせるのか？を考えてみる。
.Net界隈でドキュメントツールといえば、NDocとかSandCastleが有名どころだ。
これらを使えばソースコード上のXMLコメントをもとにして、MSDN風のドキュメントをつくることができる。
それはそれで便利なのだが、このドキュメントに表とか図とかを含めようとすると結構大変だ。


一般的にはクラスライブラリの個々APIの説明には、NDocとかSandCastleが生成したMSDN形式のドキュメントを使用し、
ライブラリ全体の構成・設計思想・クラス図やシーケンス図・使い方などの説明にはWordやExcelなどのドキュメントを作成することになると思う。


編集するという観点からみると、WordやExcelのドキュメントは便利なのだが、参照する観点からみるとナビゲーションにやや難があると思う。
(いちいちWordが起動するというのも面倒だし、複数のドキュメントをまたいだ目次がないので、目的の項目を見つけにくかったり)


そこで、このツールを使用すると複数のWordドキュメントをまとめてMSDN形式のドキュメントを生成できるので、複数のドキュメント間をナビゲートするのが簡単になる。
このツールの出力結果と、NDoc,SandCastleの出力結果をマージすることができると、概要レベルのドキュメントと詳細レベルのドキュメントを1か所で見ることができて便利なのだが。（もしかしたらできるのかも）