ソーシャル版 DITA1.1ライティングガイドを公開しました

DITA

DITAコンソーシアムジャパンのウェブサイトで、ソーシャル版 DITA1.1ライティングガイドを公開しました。

公開の目的は、

  • DITA1.2ライティングガイド作成に向けての改善要望の収集
  • ソーシャルドキュメントの可能性の検証

の２つです。

みなさん、どんどん書き込みをお願いします<(_ _)>

欧米では、Autodesk、Alfrescoといった先進的な企業が、自社製品のマニュアルをソーシャルドキュメント（Alfrescoはクラウドドキュメントと呼んでいます）として公開し、ユーザーからのフィードバックを集めると同時に、マニュアルをマーケティングに活用する試みが始まっています。
ソーシャルドキュメントは、マニュアルの可能性を広げる有効な手段だと思います。以前から、DITAはインターネットと相性が良いと考えていましたが、このソーシャルドキュメントが良い実例になりそうです。

iBooksの進化

DITA EPUB

前々から欲しかったiPad miniを、ようやく手に入れました。前にも記事を書きましたが、DITA4Publisherを使えば、DITAドキュメントから簡単にEPUBが生成できます。私はもっぱら、oXygenにバンドルされたDITA4Publisherを使っています。タブレットも随分普及したことだし、DITA1.1 ライティング・ガイドのEPUB版を公開したいなぁと思って、以前作成したEPUBをiPad miniで見てみました。


久々のiBooks。バージョンアップがかなり進んだので、「どうなってるのやら」と思って見てみたら、ビックリです。図や表の表示が、スバラしくなっているではありませんか！！
こんな感じの小さくて見にくい図があっても大丈夫。

図をダブルタップすると、図だけが表示され、ピンチイン、ピンチアウトで自由に大きさを変更できます。

驚いたのが、この拡大・縮小は、図だけではなく、表までもできちゃうんです。表は図として書いた表ではなく、DITAではCALS Table、HTMLではtable要素に変換されている表です。タブレットのような狭いディスプレイに大きな表を表示すると、こんな感じになりがちです。

表をダブルタップすると、表全体が１つの図のように表示されて、ピンチイン、ピンチアウトが自由にできるんです。

iBooksがここまで進化しているとは思いませんでした。
AndoroidのEPUB Readerではここまでできるのでしょうか？
誰か知っていたら教えてください。

なお、DITA1.1ライティングガイドのEPUB版は、DITAコンソーシアムジャパン Webサイトの公開資料からダウンロード可能です。

「ソーシャルマニュアル」という解

DITA jQuery

昨年、文書管理システムで有名なAlfrescoがクラウドサービスを始めました。システムにログインして、オンラインヘルプを見たら、「Alfresco Cloud Documentation」という名前の、これまでのマニュアルとはちょっと違う、斬新なオンラインヘルプが現れました。
Alfresco Cloud Documentation
オンラインヘルプ＋動画マニュアル＋ブログ＋ソーシャルメディアといった感じのヘルプです。「オンラインならでは」の機能をふんだんに盛り込んでいることに関心しました。このヘルプはもちろんDITAを使って作られています。
この発見と前後してoXygenV14がリリースされ、WebHelp with Feedbackが出力可能になりました。調べてみると、どうやらAlfrescoのオンラインヘルプは、oXygenV14のWebHelp with Feedbackをカスタマイズして作成しているようです。
DITAの導入が進んでいる欧米では、こういう「オンラインならでは」の付加価値を加えたマニュアル制作が盛んになってきています。このヘルプを見ると、「何かわからないことがあったとき」、「何か困ったことがあったとき」に見るという従来のヘルプの域を超えて、「製品の魅力を知ってもらう」という製品プロモーションの領域に踏み込んでいるように思えます。
従来のマニュアルが、問題が発生したときに「ここに書いてあるでしょ」と言い訳するための「守り」の存在だったのに対し、これらのマニュアルは「この製品ではこんなことができる、便利でしょ」とユーザーを引き込むための「攻め」の存在に転じているような気がします。こういうマニュアルのあり方が、今後は増えていくような気がします。インターネットを検索すると、製品の便利な使い方を紹介したトピックがヒットして、それが製品の購入につながるというのは画期的なことではないでしょうか。そうすれば、世の経営者ももっとマニュアルに力を入れようという気になるかもしれません。
…てなことを考えて、「ソーシャルマニュアル」とでも言うべきマニュアルを試作してみました。
DITA1.1ライティングガイド
DITAコンソーシアムジャパンのウェブサイトからの公開を目指したいと考えていますが、とりあえずお試しということで。

WebHelp with Feedback

DITA

oXygen Ver14から、WebHelp with Feedbackというパブリッシング形式が追加されました。どういう形式の出力なのかは、百聞は一見にしかず、oXygenそのもののオンラインヘルプを見てみてください。
http://www.oxygenxml.com/doc/ug-author/

ご覧いただくとおわかりになるように、オンラインヘルプのトピックに対して、ブログのようにコメントが書き込めるようになります。マニュアルについて顧客からのフィードバックを収集したり、顧客からのピンポイントの質問にリアルタイムで答えたりできます。

面白そうなので、早速試してみようと思い立ったのが、かれこれ１か月前。当然、簡単に動くだろうと思っていたら、ハマってしまいました。

oXygenのサポートとのやり取りの結果、今日、ようやく問題の原因をつきとめました。WebHelp with FeedbackのJavaScriptファイルの1つにBOM(Byte Order Mark)が付いていて、AntスクリプトでそのJavaScriptファイルをコピーすると、BOMの部分が化けてしまうというのが原因でした。問題のJavaScriptファイルは、下記です。
C:\Program Files\Oxygen XML Editor 14\frameworks\dita\DITA-OT\plugins\com.oxygenxml.webhelp\oxygen-webhelp\resources\js\jquery.realperson.js
このJavaScriptファイルをBOMなしで保存し直すことにより、無事、WebHelp with Feedbackが動くようになりました。
こんな感じで表示されます。

「DITA Generator」のページにおどろき!!

DITA1.2

Yahoo! DITA Users Groupのメールを見ていて、すばらしいページがあることを知りました。

その名は、DITA Generator

「DITA-OTのPDF出力をカスタマイズしたいんだけど。。。」というあるユーザーからのポストに、「Style plug-in generationは試してみた？」とのレスポンスがあったのがきっかけで見つけたページ。この「Style plug-in generation」だけでも十分すばらしいのですが、その他にも
・structural specialization
・shell DTD
・domain attribute specialization
といった、DITAの超エキスパートでなければ手が出せないようなカスタマイズを、いとも簡単に実現するためのサービスが無料で提供されています。

「DITA Generator」という名前から、「DITAのコンテンツを生成してくれるサービス？？」と一瞬誤解しそうですが、そうではなくて、DITA-OTのプラグイン（あるいはプラグインのスタブ）を自動生成したり、特殊化したDTDを自動生成したりしてくれるソフトウェアです。

さらに調べてみると、この「DITA Generator」はオープンソース・プロジェクトであることが分かりました。GitHubに登録されたプロジェクトで、Pythonでコーディングされているそうです。

dita-generator

特殊化したDTDやDocument Type Shellの生成については、まだ試していませんが、「Style plug-in generation」は少し試してみました。「Style plug-in generation」は、DITA-OTのPDF生成をカスタマイズするのに十分実用的ですが、その他、

  • XSL-FOの基本を理解する
  • DITA-OTのプラグインの作り方を理解する

のにも最適です。

是非、試してみてください。

こういったソフトウェアが作れるのは、DITA-OTを含むDITAアーキテクチャの

  • オープン性
  • 柔軟性
  • 拡張容易性

の証明ではないかと思います。

spectitle属性を使うべきか

DITA1.2

DITA1.2から、section要素にspectitle属性が指定できるようになりました。DITA1.1のときは、セクション見出しを書くのにtitle要素を使っていましたが、Kimberさんによるとspectitle属性を使うのがお奨めだそうです。
これにはちょっと抵抗があります。というのは、翻訳対象になるテキストを属性に入れると、トラブルの種になるからです。特殊化の予定がないのであれば、無理してspectitle属性を使うより、従来どおりtitle要素を使っておいた方がいいように思います。

【spectitle属性を指定したトピックの例】

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE reference PUBLIC "-//OASIS//DTD DITA Reference//EN" "reference.dtd">
<reference id="shomenuchi-ikkyo" xml:lang="ja-jp">
  <title>正面打 一教</title>
  <shortdesc><term>正面打</term>の攻撃をかわすための、最も基本の型 (<term>一教</term>)です。</shortdesc>
  <refbody>
    <section spectitle="説明図">
      <p><term>受け</term>が<term>投げ</term>の頭の上を攻撃してくるので、投げは内側に入り身して、両手で受けの手首と肘の上をつかみ、腕を受け止めます。投げは受けの腕を下に払い、標準の<term>一教</term>の型に極めます。この技では、受けを<term>表</term>または<term>裏</term>に極めることができます。</p>
    </section>
    <section spectitle="解説図">
      <fig>
        <image href="graphics/shomenuchi-ikkyo-01.jpg">
          <alt>攻撃に対する基本の対処である正面打 一教</alt>
        </image>
      </fig>
    </section>
    <section spectitle="ビデオ">
      <p>ビデオなし。</p>
    </section>
  </refbody>
</reference>

【上記トピックをWebHelpに変換した結果】

テキストファイルの指定に従ってExcelのシートをコピーする

PC関連

Excelで集計処理をするのに、ワークシートをたくさんコピーする必要があったので、マクロを書きました。テキストファイルにワークシートの名前を列挙し、そのテキストファイルに従ってワークシートをコピーするマクロです。
ワークシート名を列挙したファイル名は、"branches.txt"固定です。アクティブなワークシートをコピーします。あらかじめ、ブックに"集計"という名前のワークシートを作っていることを前提にしています。

' アクティブ・ワークシートをコピーするマクロ
' コピー先のシート名はテキストファイル(branches.txt)から読み込む

Sub copysheet()
    Dim buf As String, n As Long, fPath As String
    
    fPath = ActiveWorkbook.Path & "\" & ".\branches.txt"
    Open fPath For Input As #1
        Do Until EOF(1)
            Line Input #1, buf
            buf = Trim(buf)     ' 先頭と末尾の空白類を削除
            If Len(buf) > 1 Then
                n = n + 1
                ActiveSheet.Copy before:=Sheets("集計")  ' 「集計」シートの前に追加
                ActiveSheet.Name = buf
            End If
        Loop
    Close #1
    MsgBox ("作成したシート数 = " & Str(n))
End Sub