なぜxrefはダメなのか?

DITAのxrefといっても種類がいろいろあって、他のtopicを参照するものや、自身または他のtopicのtable、figを参照するもの、ol/liを参照するもの、idつきのfnを参照するもの(脚注参照)などいろいろあります.前者2つは該当の要素の子のtitle要素のコンテンツを該当箇所に表示してページ数もだしてやります.ol/liを参照するものは、liにつけられる番号を表示します.(たいていtaskのstepです)脚注参照は、参照先脚注の脚注記号の"(*1)"などを出します.
 
DocBookの場合なんかはトピック志向ではないので、他の章、節、項を参照するxrefをバンバン使います.でもDITAはある意味このような使い方を否定します.もちろん文書要素としてxrefは使えちゃうんですが、topicの最後にrelated-linksという要素があり、ここでこのtopicに関連するリンクをまとめて記述します.
 
なぜこのような仕組みになっているかというと、それはtopicの「完読性」を高めることが目的です.
 
で、仕様書を書いているうちに、related-linksのところに来て、お客様にxrefがなぜダメで、related-linksを使わなければならないのか説明しなければならなくなりました.
 
「何故xrefはダメなのか?」
 
これを説明しろといわれると、DITAの根本的な思想にもかかわるところなので、そう簡単に説明をかけません.そういうときこそDITAの本を読めば?と思っていろいろ見たのですが、今まで買っては「積読」してあった本にはなかなか書いてありません.やっと見つけ出したのが、去年買ってほったらかしにしていた「DITA Best Practices」でした.なぜほったらかしになったかというと、どのようなDITA本でも適切なサンプルをつけています.例えば「DITA101」だとクスコスサラダの作り方がサンプルになっています.ところが「DITA Best Practices」は最初のサンプルが、"Nuclear fusion as a power source"(動力源としての核融合)というもので、やたら物騒な代物でした.これを見ただけで当時福島の原発事故の後だったので読む意欲が萎えてしまい、ほったらかしになっていたのです.
 
DITA Best Practices: A Roadmap for Writing, Editing, and Architecting in DITA
http://www.amazon.co.jp/DITA-Best-Practices-Roadmap-Architecting/dp/0132480522/
 
イメージ 1

今回見直したのですが、他の本にない解説が書いてあります.例えば、何故(xrefを使った)リンクを避けるべきかについて、このように説明されています.
 
あなたはインラインリンク(訳注:xrefのこと)をつかうのを注意しなければなりません:それら は保守が難しく、ユーザーを混乱させかねません.個々のリンクは、インラインであれまた別の種類であっても、有用で、適切でなければなりませ ん.そうでなければ、あなたがせっかく注意深く構築したWEBの情報は(訳注:DITAからHTML出力を想定している)わかりづらい迷路に なってしまうでしょう.
 
・インラインリンクは中断を伴います: それらは、読み手の文章を読む流れを中断させます.何故ならばそれらは現在のトピックを読み終える前に、読み手を他のトピックへと導くからです.
・インラインリンクはtopic間の依存性を作り出します: トピック 間の依存性は保守が難しく、topicを拡張して再利用するのを制限します.
・インラインリンクは読み手のナビゲーションを理解しにくくします:たく さんのインラインリンクはたいていtopicの構成の問題点を示しています.もし「See topic X for more information」と段落毎に書かれているのをあなた自身が見つけたら、topicの構成と目的を再度評価して下さい.たぶんそれは書き直さねばな らないでしょう.
・インラインリンクはコンテンツを過重にします:リンクはユーザーに何が 重要なのかを知らせます.「Restriction」や「Important」というラベルが書かれた段落と同じです.リンクの多用 は、このようなラベルの多用と似ています.すべてが重要であるとされ、結局何も重要ではありません.
 
related-linksはtopicの最後に位置しますが、通常はtopic毎にオーサリングするのではなく、mapにreltableというのを書くとDITA-OTが参照されているtopic/related-linksへ自動的に展開してくれます.なので、reltableでやるかどうかは、DITAをやる上で非常に重要な選択になります.この本ではreltableの優位性についてこのように書かれています.
 
関連テーブル(reltable)は執筆する上で以下の有利な点も持っています.
 
・集中したリンク管理: 関連テーブル(reltable)はDITAのmapファイルだけに書くことを許されます.関連テーブルはtopic同士のリンクの配置を簡単にします. 何故ならリンクが一か所で書かれ個々のtopicで書かれることがないからです.
・保守の工数削減: topic同士のリンクが簡単に記述でき、リンクを直したり更新したりするのも中央の集中した箇所(reltable)からできます.個々のtopicを 探しだすのより楽です.
・再利用性の向上: リンクをtopicの内部でなくDITA mapから作り出すので、topicは他のファイルへの依存度が減ります.依存度が減ることにより、topicの再利用性の向上をはかることができます.
 
あるお客様は果敢に挑戦されて、ほとんどすべてのリンクをreltableで運用してtopic中のxrefを駆逐されています.
 
「DITA Best Practices」いい感じかもしれません.今回非常に勉強になりました.