I love software!

« これ以上ないくらい分かりやすいDITA入門（当社比） | メイン | DITA超入門 ― フィルタリング　トピックを効率的につくる！ »

2011年09月27日

DITA超入門 ― トピックとマップ 避けては通れないはじめの一歩

こんにちは。昨日に引き続きDITAのお話です。今日は、DITAの初めの一歩として避けては通れないトピックとマップについて触れてみます。
DITAではひとつのドキュメントを作るにあたり、（複数の）トピックと（ひとつの）マップを組み合わせて使います。

■トピック

トピックにはドキュメントのコンテンツを記述します。たとえば次のようになります。

＜topic id="GoalOfDITA＞
　＜title＞DITAのめざすもの＜/title＞
　＜body＞
　　＜p＞DITAの目的は次のとおりです＜/p＞
　　＜ul＞
　　　　＜li＞データ再利用性の向上＜/li＞
　　　　＜li＞ワンソースマルチユース＜/li＞
　　　　＜li＞翻訳の効率化
　　＜/ul＞
　＜/body＞
＜/topic＞

なんだかどこかで見たことあるような..ないような...
そう、雰囲気的にはHTMLにそっくりです。とりあえずここまではあまりハードルは高くなさそうですね。
ひとつのトピックファイルにはひとつのトピック（話題）しか書かない、ということが推奨されています。ひとつのトピックファイルの中でだらだらといくつもの話題に触れるのはよしましょう、ということですね。そのため、ひとつのドキュメントを制作するにあたり必然的に複数のトピックファイルを用意することになります。

■マップ

上記の（複数の）トピックファイルをひとつにまとめることがマップの役割です。マップを使ってトピックの出力順やトピック間の階層構造を決めることになります。たとえば次のようになります。

＜map title="取扱説明書"＞
　　＜topicref href="はじめに.dita" /＞
　　＜topicref href="電源の入れ方.dita" /＞
　　＜topicref href="ラジオの聴き方.dita" /＞
　　　：
　　　：
＜/map＞

この例は超基本的な例です。この他にさまざまな機能が用意されています。個人的にはマップを制することがDITAを成功へ導く秘訣だと感じていますが、ま、最初の一歩としては上記で十分でしょう。

マップとトピックの関係を図式化すると次のようになります。

この図を見て分かるように、マニュアルの種類だけマップを作り、それぞれのマップから１セットのトピックファイル（群）を共有参照する、というのがDITAの基本的な考え方です。

■トピック指向の執筆

ワードやdocbookでマニュアルを書くときは、１つのファイルに１冊分のコンテンツを丸ごと記述することになりますが、DITAでは複数のトピックファイルに分割して記述することになります（モジュール化）。こうすることで各トピックの再利用性の向上を図るわけですが、このことにより、執筆の仕方を今までとは変えなくてはならないことがあります。
たとえば「ラジオの聴き方」を書いたトピックの中では「すでに述べた方法で電源を入れた後に・・・」という書き方は避けた方がいいでしょう。なぜならマップの書き方次第では「すでに述べた」とは言い切れないからです。後で述べるかもしれませんし、そもそもどこにも述べない可能性もあります。つまり文脈依存の書き方は避けた方がよい、ということになります。これをトピック指向と言います。

■ショートデスクリプションの奨め

トピック内にショートデスクリプション（要約）を書くことが推奨されています。たとえば次のようになります。

＜topic id="GoalOfDITA＞
　＜title>DITAのめざすもの＜/title＞
　＜shortdesc＞DITAによってマニュアル制作の効率化を望めます＜/shortdesc＞
　＜body＞
　　＜p＞DITAの目的は次のとおりです＜/p＞
　　＜ul＞
　　　　＜li＞データ再利用性の向上＜/li＞
　　　　＜li＞ワンソースマルチユース＜/li＞
　　　　＜li＞翻訳の効率化＜/li＞
　　＜/ul＞
　＜/body＞
＜/topic＞

こうすることでHTMLにした場合など、アンカー文字列にマウスホバーしたときに要約をポップアップさせたり、検索結果として要約のみをリストアップすることができるようになります。
とても小さなトピックの場合、要約を書くことによって本文に書くことがなくなってしまう、という心配もあるかもしれませんが、そのときは本文の方を空にします。それほど要約が重要視されているということですね。
各トピックの要約を読んだだけで製品の全体像がそこそこ分かってしまう、という形が理想的なのかもしれません。ですので、

　＜shortdesc＞ここではxxxについて述べます＜/shortdesc＞

というような要約はご法度です。

では、また明日。

投稿者 taishii : 2011年09月27日 11:30

トラックバック

このエントリーのトラックバックURL:
http://blog.antenna.co.jp/PDFTool/mt-tbng2.cgi/1743

コメント

コメントしてください