DITA採用事例（XMetaLのFAQをDITAで作る）

DITA image

アンテナハウスはXMetaLのFAQのページをDITAで執筆しました。実際の成果物のイメージは下記をご覧ください。

このようにXMetaL V6.0からV10.0までのすべてのバージョンのFAQを公開しています。お客様の諸事情で古いバージョンをお使いの方も多くいらっしゃいます。ですので最新バージョンだけでなく古いバージョンのFAQについてもメンテナンスして行く必要があります。

XMetaLのすべてのバージョンのFAQを効率よくメンテナンスするためにDITAを採用しました。

結果として、管理すべきトピック数をおおよそ半減させることができました。

ちなみにDITA導入前に管理していたトピック数は次のとおりです。
V6：19個
V7：21個
V8：34個
V9：25個
V10：25個
合計 124個

それに対しDITA導入後に管理しているトピック数は次のとおりです。
全バージョンで：67個

以前は、XMetaLのバージョン毎にFAQのセットをXMLで作っていました（当然、内容の重複するトピックがたくさん存在します）。このためメンテナンスが必要になったとき、複数のトピックに同じ内容の修正をしなければいけないケースがありました。

たとえばV9.0とV10.0で同じ内容のFAQがあったとします。そしてこのFAQを修正する必要が出てきたとき、「2つのまったく同じ内容のトピック」に「まったく同じ修正」を入れる必要があったわけです。

また、XMetaLの新バージョンが出てきたとき、直前のバージョンのFAQのセットをごっそりとコピーして新たなFAQのセットを用意しなければいけません。メンテナンスしなければいけないトピックは増える一方です。

XMetaLのバージョン毎のFAQを見比べてみると、類似箇所が多いことに気がつきました。また、完全に同じではなくても、工夫をすればバージョン番号等のキーワードやイメージファイルの差し替え等でひとつのFAQインスタンスを複数のバージョンで使い回しができそうに思えました。

そこでDITAの登場です。DITAはひとつのトピックファイルを複数箇所で再利用する仕組みをいくつか持っています。この仕組みを利用すれば格段にメンテナンス効率を上げられるのではないか、そのように考えたわけです。

DITAを採用するにあたって次のような目標を定めました。

どのようなトピックファイルやマップファイルを作ったか、以下に概要を述べます。

以下の2つのサンプルは、トラブルシューティング情報タイプを使用して作成しています。2016年1月、DITA1.3が正式公開されましたが、トラブルシューティングはこの1.3より実装されたものです。

サンプル1

トピックファイルの中にXMetaLのバージョン番号を直書きしてしまうと、そのトピックファイルはバージョン間で共有できなくなってしまうので、ここでは

と @keyref を使って間接的にXMetaLのバージョン番号を指定しています。こうすることで、ビルドしたときに正しいXMetaLのバージョン番号に自動的に置き換わるようにしています。結果は次のとおりです。

※DITAに詳しい方なら「@keyrefを使っただけでそこまでできるのかな？」と疑問に思われた方もいらっしゃると思います。おっしゃるとおりです。実際はDITAの条件処理も合わせて利用しています。

サンプル2

ここでの注目点は

のところです。

XMetaLのV8.0とV10.0には日本語版があるのですが、V9.0には日本語版がありません。つまり同じ意味を現わす文言でもGUI上ではバージョンによって日本語だったり英語だったりするわけです。

@keyref="TrackChanges" とすることで、XMetaLが日本語対応しているバージョンの場合には日本語の、日本語対応していないバージョンの場合には英語の文言が自動的に選択されるようにしました。

※これも前述のサンプルと同じように@keyrefを使っただけでは実現できません。DITAの条件処理も合わせて利用しています。

期待する見栄えを得るために、通常はCSSやスタイルシート側にその見栄えを実現する処理を記述することになります。しかし、そうは言っても当初予想していなかった見栄えがどうしても欲しくなることがあります。

そこで、社内で「ah-dita」と呼んでいる特殊化を採用することにしました。

上図でcss:prop属性を使っていますが、これが特殊化で用意した属性です。属性値はCSS記法で記述します。

css:prop属性を使うことで下記の緑色で囲まれた部分のような体裁を得ることができます。

下記はマップファイルの先頭部分です。

上から順番に見て行きましょう。

条件処理によるフィルタリング（XMetaLのバージョンによるトピック選択）を容易にするために subject scheme を使いました。このことでproduct属性の内容検証もきちんとできるという副産物を得ることができます。
XMetaLのバージョン番号等、バージョンごとに内容が異なるキーワードをまとめたファイルです。上記のトピックファイルの説明の中のサンプル1で利用しています。
日本語対応しているXMetaLの日本語キーワードをまとめたファイルです。トピックファイルの説明の中のサンプル2で利用しています。（V6.0とV8.0で採用されます）
日本語対応していないXMetaLの英語キーワードをまとめたファイルです。トピックファイルの説明の中のサンプル2で利用しています。（V7.0、V9.0、V10.0で採用されます）
トピックファイルへのリンクです（V7.0～V10.0で選択されます）
トピックファイルへのリンクです（V8.0でのみ選択されます）

このようにXMetaLのバージョンの違いによる出力結果の切り替えは原則としてマップファイルでコントロールできるようにしました。

お問い合わせ