PDF、組版と文書変換のアンテナハウス株式会社

サイトマップ
hr トップ
ページ
hr デスクトップ
製品情報
hr システム
製品情報
hr DITA
サービス
hr 電子書籍
サービス
hr サポート hr 製品の購入
について
hr お問い合わせ hr 会社案内 hr

スペーサー

DITA採用事例(XMetaLのFAQをDITAで作る)

要約

アンテナハウスは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個

DITA採用前

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

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

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

DITA採用の背景

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

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

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

  • XMetaLのバージョン間で同じ内容のFAQはひとつのトピックファイルにする
  • XMetaLのバージョン間で多少内容が異なったとしても可能な限りひとつのトピックファイルにする
  • XMetaLのバージョン間で異なる情報はマップファイル中に閉じ込めてしまう(マップファイルは全バージョンを通じてひとつしか用意しない)

実際の内容

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

トピックファイル

トラブルシューティング情報タイプ

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


サンプル1

下記はXMetaL V7.0~V10.0の4バージョンで共通に使われるトピックファイルの一部です。
ダウンロード販売

トピックファイルの中にXMetaLのバージョン番号を直書きしてしまうと、そのトピックファイルはバージョン間で共有できなくなってしまうので、ここでは
<ph keyref="xm-current"/>
と @keyref を使って間接的にXMetaLのバージョン番号を指定しています。@keyref="xm-current"とすることで、ビルドしたときに正しいXMetaLのバージョン番号に自動的に置き換わるようにしています。結果は次のとおりです。

V7.0での出力結果
ダウンロード販売V7

V10.0での出力結果
ダウンロード販売V10

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


サンプル2

下記はXMetaL V8.0~V10.0の3バージョンで共通に使われるトピックファイルの一部です。
履歴保存

ここでの注目点は
<ph keyref="TrackChanges"/>
のところです。

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

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

V8.0での出力結果
履歴保存V8

V9.0での出力結果
履歴保存V9

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


ah-dita特殊化

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

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

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

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


マップファイル

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

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

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

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

スペース
トップページサポートお問い合わせ会社案内
サイトマップ個人情報保護の考え方とお願い
Copyright Antenna House, Inc. All rights reserved.
Antenna House is a trademark of Antenna House, Inc.