やってはいけないDITA(その1)

DITA(Darwin Typing Architecture)の導入があちこちの組織・企業で行われています.もう今ではサブスクリプションばやりで、CMSも必要な機能だけ購入して必要な規模だけ使うので、昔は一番経営陣を納得させるのに苦労したCMS導入ってもはや問題にならないんだそうです.一番の問題はXSLTスタイルシートを作るのに必要なお金が高いんだとのこと.それでお給料をいただいている身からすると、何か悪いことでもしているのか?と思わず自答してしまいます.
でもXSLTスタイルシートってそう簡単には作れないです.そもそもお客様はCMS導入でトレーニングを積んで、コンテンツをコンバージョンしたりして作って、それで「ああしたい」「こうしたい」を私たちにぶつけてくるのですから、正直なところあんまりDITAに習熟していないです.
だから、とかくDITA本来というかDITAの仕様に決められたものを、「ご自分なりに解釈して」ここの出力はこうしてほしい、ああしてほしいと仕様がどんどん膨らみます.今回はそのような場合によく出てくる、ちゃっと首をかしげるパターンを紹介します.

「navtitleで出したい」

一番出てくるのが、topic/titleを表示するんじゃなくて、ある場合はマップのtopicref/topicmeta/navtitleもしくはtopicref/@navtitleを代わりに出力してくれ!というものです.最初は事情がとんとわからないかったのですが、これは例えば、ユーザーニュアルとサービスマニュアルで、たまたま同じトピックを再利用して使いたい、でもユーザーニュアルには大本のサービスマニュアルで出していたtopic/titleではなくて、マップに書いたnavtitleを出したいということのようです.

f:id:toshi_xt500:20220401101739p:plain

そういえば気が付いたんですが、このような要望は今まで結構ありました.(少なくとも4~5回は)

でもですね、たぶん今のDITA-OT(DITA Open Tool Kit)ではバグがあって、マップの側のtopic/topicmeta/navtitleをtopic/titleで上書きしちゃう場合があるんです.

topicmeta/navtitle is overridden by topic/title even if @locktitle="yes" #3708
https://github.com/dita-ot/dita-ot/issues/3708

Preserve topicref/topicmeta/navtitle when @locktitle is enabled #3746
https://github.com/dita-ot/dita-ot/pull/3746

お客さんからの要望もあって、必死にJavaのコード調べてプルリクエストをDITA-OTのプロジェクトに上げたんですが、マージの前のセルフチェックで何故かエラーが出てしまったためか採用してもらえせんでした.なので安心してnavtitleは使えません.もちろん手元でのテストは万全だったんですが、何故エラーになってしまったかは知るすべもありません.

で逆に何故こんなお話がお客様から出るのか?と考えたんですが、それは実はお客様がトピックレベルの共有(再利用)しかしていないから、そのまま何とかするために言われた要求であるということです.タイトルだけ変えたいということは翻って、topic/bodyは同じで良いことになります.

ならばライブラリ的なトピックを作って、サービスマニュアルのトピックからも、ユーザーマニュアルのトピックからもそのbodyの配下の要素をconrefなりconkeyrefなりしていただく、そして各々にふさわしいtopic/titleをつけていただく.で万事解決します.以下はdivで要素を再利用する例です.

f:id:toshi_xt500:20220401101645p:plain

これはそれまでの、Microsoft Wordなんかでパブリケーションをしていたステップから始まったとすると、まずマップとトピックで書くというのはDITAの基本なので、まずそれはいいんですが、そこから先に実は再利用はまったく進んでいないということになります.DITAは「トピックの再利用」がすべてではありません.もっともっと工夫すれば、自在にコンテンツを操れます.でもこういうことを理解するのはお客さんにとっては至難の業のようです.

なかなかDITAの再利用戦略を立てるって大変です.汗をかかなければなりません.でももしその努力を怠って、延々とトピックを書き続けていたら、それは単にそれまでやっていたMicrosoft Wordが形だけトピックに変わって、CMSにひたすら蓄積されているだけのことになります.

つまり、自らのコンテンツを支配(管理)するのではなくて、実はいまだにたまり続けるコンテンツに支配され続けていることに気が付かないだけなんですね.日本の企業ってそういうところは本当に閉鎖的で、せっかく世界規格であるDITAを使っても学ぼうとしない、外部からの指摘に耳を傾けないです.

日本でもDCJ(DITA Consortium Japan)で紹介された先駆的な企業さんは本当にこういう点で努力して汗をかいておられます. はたから見ていても尊敬するくらい喧々諤々と議論して自分たちのコンテンツを良くすることに真剣です.

そういう努力をしないと、数年前のDCJ主催のDITA Festaで紹介された有名な言葉「なんちゃってDITA」の導入になってしまうのでしょう.