株式会社インターネットイニシアティブプロダクト推進部

山口 貴史

Confluence と DITA によるWeb マニュアル作成フロー

‐ 2 ‐

Confluence 使ってます（どっぷり浸かっています） 導入事例が載りました

• http://www.ricksoft.jp/case-studies/iij

‐ 3 ‐

自己紹介

IIJ 勤務• ドキュメント書き• 製品 / サービスのサポート担当• 非プログラマー

• 簡単なスクリプトくらいなら…

休日はネコとかカモとか探してます

‐ 4 ‐

本日のネタ 製品マニュアルの編集環境として Confluence を活用する事例を紹

介します。• Word も InDesign もテキストエディタも要らなくなります

• メンテナーには速い PC と高機能な XML エディタを

書き溜めたコンテンツをいかに再利用するか

‐ 5 ‐

ある日の注文 シンプルな Web （ HTML ）マニュアルを作りたい 変更をすぐに反映したい 専門技術なしで編集したい 変更管理もしたい

Confluence なら誰でも書けるよね• 絵も Gliffy で描けるし• じゃぁ何とかするので Confluence で原稿書いてください

‐ 6 ‐

できたモノ

‐ 7 ‐

宣伝 SlicePoint 提供開始しました

‐ 8 ‐

事例その１ SlicePoint FAQ とユーザーガイド（ Web マニュアル）

• http://www.slicepoint.jp/

Confluence で原稿書いてます

‐ 9 ‐

宣伝その２ クラウドサービスもあります

• Confluence や SlicePoint も導入できます

‐ 10 ‐

事例その２ IIJ GIO ホスティングパッケージサービス API Reference

• http://manual.iij.jp/gp/gpapi/

Confluence で原稿書いてます

‐ 11 ‐

Confluence と DITA

‐ 12 ‐

いきさつ シンプルな作業フローで Web マニュアルを作りたい Confluence で書いて HTML エクスポートしては？ PDF も出せま

す シンプルとは言っても手は入れたい（レイアウトとか） うちの製品でそういうの（ Web マニュアル内製）やってたよね？ それは DITA を使ってます。 DITA は書き手の訓練が少々必要です

DITA のマークアップは XML だね Confluence のストレージフォーマットも XML らしいね

変換でなんとかなるんじゃない？

‐ 13 ‐

宣伝 件のうちの製品

• ルータ製品 SEIL （ザイル）シリーズ

‐ 14 ‐

DITA 事例 SEIL シリーズ技術情報（ Web マニュアル）

• http://www.seil.jp/support/

DITA で書いてますConfluence 使ってません（まだ）

昔は TeX > PDF でした

多機種展開するプロダクトにはよくマッチします

‐ 15 ‐

DITA って？ Darwin Information Typing Architecture (DITA)

• IBM 社がマニュアル製作のために（全部置き換える前提で）考えた本気仕様• OASIS に仕様を寄付• XML ベースのマークアップ記法

• 同一ソースから色々なフォーマットでアウトプットできる• HTML, PDF, ePub, Windows Help, etc…

推進団体• DITA コンソーシアムジャパン• http://dita-jp.org/

DITA Open Toolkit• http://dita-ot.github.io/• DITA のオープンソース実装

日本語の導入情報もぼちぼち増えてきました

‐ 16 ‐

Confluence と DITA

ドキュメント作成ツールとしてみた場合… Confluence は CMS

• WordPress, MovableType, Wiki, etc…• 文章の入力や管理、閲覧を支援するツール• Web フォームなどで編集する

• マークアップの知識が不要• がっちりした独自システムで提供され、文書データはデータベースの中

DITA は変換システム• TeX, DocBook, Sphinx, etc…• テキスト（ソース）を任意の文書（ファイル）に変換するツール• テキストエディタや XML エディタで編集する

• マークアップの知識が必要• ツール自体を部品として組み込める。文書データは個別のテキストファイル• 大抵、テーブル（表）を書くときに泣きます

• 対応した WISYWIG 系のエディタが導入できると便利

‐ 17 ‐

DITA を扱える CMS 文書の作成・管理が主軸になってしまう

• 専門のエディタと連携した総合環境的なシステム• Confluence のような手軽さやコミュニティ機能とは別路線

高価なのです…

‐ 18 ‐

DITA の利点 機械的処理に有利

• XML なので大抵の処理系で扱える。• XHTML より構造化ルールが厳格

マニュアル作成のために作られた仕様である• 書式に従うだけでマニュアルっぽくなる

• （書き手の個性を出しにくい）

翻訳（多言語対応）に有利• 文章の body 部分しか持たず、レイアウト要素は文章と切り離されているた

め、重複部分の翻訳が必要無い• XML で構造化されているため、除外処理が容易（翻訳支援ソフト次第）

‐ 19 ‐

使用ツールと環境 Confluence

• 編集環境

DITA Open Toolkit (DITA-OT)• HTML マニュアルの生成

Confluence Wiki の内容を DITA に変換するスクリプト• 自作（ XSLT ）

Git (GitHub Enterprise)• 生成物のバージョン管理（省略）

Jenkins• 自動生成・自動デプロイ（省略）

ビルド用ホスト• DITA-OT が動く Java 実行環境 (JRE) があればWindows PC でもよい

‐ 20 ‐

（概ね）なんとかなりました。 Confluence にスペースを作ってマニュアルを書く スペースを XML エクスポートする XSLT で DITA フォーマットに加工する DITA Open Toolkit で HTML に変換する GitHub Enterprise でバージョン管理する 公開サーバにデプロイする

Confluence で 編集

GitHub でバージョン管理

エクスポートして料理

XSLT で DITAに

DITA で HTML に

公開サーバにデプロイ

‐ 21 ‐

舞台裏

‐ 22 ‐

もう少し踏み込みます Confluence にマニュアル作成スペースを作る Confluence からの XML エクスポート Confluence のストレージフォーマットの解析 DITAへの変換

‐ 23 ‐

Confluence のマニュアル作成スペース ふつうのスペース

• 内部的なメタ情報を少々追加（ただのテーブル）

原稿

作法とか

ワークフロー的な情報

セクションごとのメタ情報

赤入れ（指摘）は随時コメントに

テンプレートをいくつか用意

‐ 24 ‐

Confluence からの XML エクスポート (Web) Web からエクスポート

‐ 25 ‐

Confluence からの XML エクスポート (API)

/// ログインしてトークンを取得String token = (String)client.execute("confluence2.login", new Object[] {user, pass});/// エクスポート URL を取得String exportUrl = (String)client.execute("confluence2.exportSpace", new Object[] {token, spaceKey,"TYPE_XML" });

API を利用• Java を使用しています

• login メソッドでトークンを取得

• トークン、スペースキー、エクスポートタイプを指定して exportSpace

• ダウンロード URL （ ZIP ファイル）が取得できる

‐ 26 ‐

エクスポートの中身 全部入り

• バックアップデータなので当然ながら全部入っている• ページの内容（履歴も）• 添付ファイル（履歴も）• コメント• ラベル• etc…

添付ファイルが格納されているGｌ iffy の作図データも入っている

スペース内の全ページ、全履歴、メタデータ等詰まった大きな XML

エクスポート（バックアップ）に関する情報日付とかスペース名とか

‐ 27 ‐

entities.xml こんな感じ

ページっぽい

いいね！っぽい

‐ 28 ‐

手がかり ID で探索してみると

発見

それっぽい

ページの中身はまた別らしい

配下のページの ID 一覧

‐ 29 ‐

ツリーを復元する ホームページの ID を起点に、配下のページ ID を探索していく

それらしく再現できる

ページのファイル名はページ ID を使うことにした

DITA では <topicref> のネストで目次階層を表現する

‐ 30 ‐

ページ本文を調べる ボディ部分は CDATAセクションに格納されている

セクションマクロは独自 XML 表記

基本的なマークアップはHTML そのもの

（ DITA でもほぼ同じ）

‐ 31 ‐

添付ファイル 添付ファイルは厄介

添付ページごとのフォルダ（たぶん）

添付ファイルごとのフォルダ

添付ファイルのバイナリ履歴付き

ファイル名やファイル形式はentities.xml で辿る

‐ 32 ‐

添付ファイル どう繋げるか

"Page" に "Attachment"として ID が入っている

"Attachment" に ファイル名等が入っている

<p>  <ac:image>    <ri:attachment ri:filename="logout002.png" />  </ac:image></p>

本文には ファイル名で書かれている

‐ 33 ‐

DITA的応用（ FAQ ） テンプレートとコンディショナル処理

“Q” と “ A” の枠をFAQ テンプレートでつくっておく「枠ごとコピぺで増やしてね！」

ページ内の情報からDITA のフィルタ属性を埋める

HTML 出力時に付加する” class”

Confluence ライターもDITA ライターも楽々

‐ 34 ‐

課題 アウトソースしづらい

• 社内運用の Confluence に外部から接続させるのはセキュリティ的に難しい• Confluence で書いてくれるアウトソース先の捜索

メンテナーの確保• XSLT しか使っていないとはいえ、独自実装なのでメンテナンス要員は確保

しておかないとブラックボックス化してしまう

DITA を活かせていない• バリデーションの厳しい変換ツールとしての役割のみ• 目的は達せているが DITA 書きとしては物足りない

Confluence上でのメタ情報記述• ラジオボタンやセレクトボックスがほしいところ

• タスクマクロ流用では通知頻度がはんぱない…

‐ 35 ‐

勝手に宣伝 実はプロダクトもあります

• WikiWorks• http://wikiworks.jp/• ナレッジオンデマンド株式会社• Confluence を活用したドキュメンテーション・ワークフレーム

‐ 36 ‐

XML エディタ紹介 <oXygen/> XML Editor

• DITA 編集が楽になります（編集しなくて済むようになるわけですが…）• XSLT の編集と実行にも便利

‐ 37 ‐

ありがとうございました