Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

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

6,611 views

Published on

2014/02/25 #augj での発表資料です。
Confluenceのストレージフォーマット(XML)をDITA変換してWebマニュアルを作成した事例を紹介します。

Published in: Self Improvement

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

  1. 1. Confluence と DITA による Webマニュアル作成フロー 株式会社インターネットイニシアティブ プロダクト推進部 山口 貴史
  2. 2. Confluence使ってます(どっぷり浸かっていま す)  導入事例が載りました • http://www.ricksoft.jp/case-studies/iij ‐ 2 ‐
  3. 3. 自己紹介  IIJ勤務 • ドキュメント書き • 製品/サービスのサポート担当 • 非プログラマー • 簡単なスクリプトくらいなら…  休日はネコとかカモとか探してます ‐ 3 ‐
  4. 4. 本日のネタ  製品マニュアルの編集環境としてConfluenceを活用する事例を紹介し ます。 • WordもInDesignもテキストエディタも要らなくなります • メンテナーには速いPCと高機能なXMLエディタを  書き溜めたコンテンツをいかに再利用するか ‐ 4 ‐
  5. 5. ある日の注文  シンプルなWeb(HTML)マニュアルを作りたい  変更をすぐに反映したい  専門技術なしで編集したい  変更管理もしたい  Confluenceなら誰でも書けるよね • 絵もGliffyで描けるし • じゃぁ何とかするのでConfluenceで原稿書いてください ‐ 5 ‐
  6. 6. できたモノ ‐ 6 ‐
  7. 7. 宣伝  SlicePoint 提供開始しました ‐ 7 ‐
  8. 8. 事例その1  SlicePoint FAQとユーザーガイド(Webマニュアル) • http://www.slicepoint.jp/ Confluenceで 原稿書いてます ‐ 8 ‐
  9. 9. 宣伝その2  クラウドサービスもあります • ConfluenceやSlicePointも導入できます ‐ 9 ‐
  10. 10. 事例その2  IIJ GIO ホスティングパッケージサービス API Reference • http://manual.iij.jp/gp/gpapi/ Confluenceで 原稿書いてます ‐ 10 ‐
  11. 11. Confluence と DITA ‐ 11 ‐
  12. 12. いきさつ  シンプルな作業フローでWebマニュアルを作りたい  Confluenceで書いてHTMLエクスポートしては?PDFも出せます  シンプルとは言っても手は入れたい(レイアウトとか)  うちの製品でそういうの(Webマニュアル内製)やってたよね?  それはDITAを使ってます。DITAは書き手の訓練が少々必要です  DITAのマークアップはXMLだね  ConfluenceのストレージフォーマットもXMLらしいね 変換でなんとかなるんじゃない? ‐ 12 ‐
  13. 13. 宣伝  件のうちの製品 • ルータ製品 SEIL(ザイル)シリーズ ‐ 13 ‐
  14. 14. DITA事例  SEILシリーズ技術情報(Webマニュアル) • http://www.seil.jp/support/ DITAで書いてます Confluence使ってません(まだ) 昔はTeX > PDFでした 多機種展開するプロダクトには よくマッチします ‐ 14 ‐
  15. 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のオープンソース実装 日本語の導入情報もぼちぼち増えてきました ‐ 15 ‐
  16. 16. Confluence と DITA ドキュメント作成ツールとしてみた場合…  ConfluenceはCMS • WordPress, MovableType, Wiki, etc… • 文章の入力や管理、閲覧を支援するツール • Webフォームなどで編集する • マークアップの知識が不要 • がっちりした独自システムで提供され、文書データはデータベースの中  DITAは変換システム • TeX, DocBook, Sphinx, etc… • テキスト(ソース)を任意の文書(ファイル)に変換するツール • テキストエディタやXMLエディタで編集する • マークアップの知識が必要 • ツール自体を部品として組み込める。文書データは個別のテキストファイル • 大抵、テーブル(表)を書くときに泣きます • 対応したWISYWIG系のエディタが導入できると便利 ‐ 16 ‐
  17. 17. DITAを扱えるCMS  文書の作成・管理が主軸になってしまう • 専門のエディタと連携した総合環境的なシステム • Confluenceのような手軽さやコミュニティ機能とは別路線  高価なのです… ‐ 17 ‐
  18. 18. DITAの利点  機械的処理に有利 • XMLなので大抵の処理系で扱える。 • XHTMLより構造化ルールが厳格  マニュアル作成のために作られた仕様である • 書式に従うだけでマニュアルっぽくなる • (書き手の個性を出しにくい)  翻訳(多言語対応)に有利 • 文章のbody部分しか持たず、レイアウト要素は文章と切り離されているため、 重複部分の翻訳が必要無い • XMLで構造化されているため、除外処理が容易(翻訳支援ソフト次第) ‐ 18 ‐
  19. 19. 使用ツールと環境  Confluence • 編集環境  DITA Open Toolkit (DITA-OT) • HTMLマニュアルの生成  Confluence Wiki の内容を DITA に変換するスクリプト • 自作(XSLT)  Git (GitHub Enterprise) • 生成物のバージョン管理(省略)  Jenkins • 自動生成・自動デプロイ(省略)  ビルド用ホスト • DITA-OTが動くJava実行環境(JRE)があればWindows PCでもよい ‐ 19 ‐
  20. 20. (概ね)なんとかなりました。  Confluenceにスペースを作ってマニュアルを書く  スペースをXMLエクスポートする  XSLTでDITAフォーマットに加工する  DITA Open ToolkitでHTMLに変換する  GitHub Enterpriseでバージョン管理する  公開サーバにデプロイする エクスポートして料理 公開サーバにデプロイ Confluenceで編集 XSLTでDITAに DITAでHTMLに GitHubでバージョン管理 ‐ 20 ‐
  21. 21. 舞台裏 ‐ 21 ‐
  22. 22. もう少し踏み込みます  Confluenceにマニュアル作成スペースを作る  ConfluenceからのXMLエクスポート  Confluenceのストレージフォーマットの解析  DITAへの変換 ‐ 22 ‐
  23. 23. Confluenceのマニュアル作成スペース  ふつうのスペース • 内部的なメタ情報を少々追加(ただのテーブル) テンプレートを いくつか用意 原稿 ワークフロー的な情報 作法とか セクションごとの メタ情報 赤入れ(指摘)は 随時コメントに ‐ 23 ‐
  24. 24. ConfluenceからのXMLエクスポート(Web)  Webからエクスポート ‐ 24 ‐
  25. 25. ConfluenceからのXMLエクスポート(API)  APIを利用 • Javaを使用しています /// ログインしてトークンを取得 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" } ); • loginメソッドでトークンを取得 • トークン、スペースキー、エクスポートタイプを指定してexportSpace • ダウンロードURL(ZIPファイル)が取得できる ‐ 25 ‐
  26. 26. エクスポートの中身  全部入り • バックアップデータなので当然ながら全部入っている • • • • • ページの内容(履歴も) 添付ファイル(履歴も) コメント ラベル etc… 添付ファイルが格納されている Gliffyの作図データも入っている スペース内の全ページ、全履歴、 メタデータ等詰まった大きなXML エクスポート(バックアップ)に関する情報 日付とかスペース名とか ‐ 26 ‐
  27. 27. entities.xml  こんな感じ ページっぽい いいね!っぽい ‐ 27 ‐
  28. 28. 手がかり  IDで探索してみると 発見 それっぽい 配下のページのID一覧 ページの中身はまた別らしい ‐ 28 ‐
  29. 29. ツリーを復元する  ホームページのIDを起点に、配下のページIDを探索していく それらしく再現できる DITAでは<topicref>のネストで 目次階層を表現する ページのファイル名は ページIDを使うことにした ‐ 29 ‐
  30. 30. ページ本文を調べる  ボディ部分はCDATAセクションに格納されている セクションマクロは独自XML表記 基本的なマークアップは HTMLそのもの (DITAでもほぼ同じ) ‐ 30 ‐
  31. 31. 添付ファイル  添付ファイルは厄介 添付ページごとのフォルダ(たぶん) 添付ファイルごとのフォルダ 添付ファイルのバイナリ 履歴付き ファイル名やファイル形式は entities.xml で辿る ‐ 31 ‐
  32. 32. 添付ファイル  どう繋げるか "Attachment"に ファイル名等が入っている "Page" に "Attachment" としてIDが入っている 本文には ファイル名で 書かれている <p> <ac:image> <ri:attachment ri:filename="logout002.png" /> </ac:image> </p> ‐ 32 ‐
  33. 33. DITA的応用(FAQ)  テンプレートとコンディショナル処理 “Q” と “A” の枠を FAQテンプレートでつくっておく 「枠ごとコピぺで増やしてね!」 Confluenceライターも DITAライターも楽々 ページ内の情報から DITAのフィルタ属性を埋める HTML出力時に付加する”class” ‐ 33 ‐
  34. 34. 課題  アウトソースしづらい • 社内運用のConfluenceに外部から接続させるのはセキュリティ的に難しい • Confluenceで書いてくれるアウトソース先の捜索  メンテナーの確保 • XSLTしか使っていないとはいえ、独自実装なのでメンテナンス要員は確保し ておかないとブラックボックス化してしまう  DITAを活かせていない • バリデーションの厳しい変換ツールとしての役割のみ • 目的は達せているがDITA書きとしては物足りない  Confluence上でのメタ情報記述 • ラジオボタンやセレクトボックスがほしいところ • タスクマクロ流用では通知頻度がはんぱない… ‐ 34 ‐
  35. 35. 勝手に宣伝  実はプロダクトもあります • WikiWorks • http://wikiworks.jp/ • ナレッジオンデマンド株式会社 • Confluenceを活用したドキュメンテーション・ワークフレーム ‐ 35 ‐
  36. 36. XMLエディタ紹介  <oXygen/> XML Editor • DITA編集が楽になります(編集しなくて済むようになるわけですが…) • XSLTの編集と実行にも便利 ‐ 36 ‐
  37. 37. ありがとうございました ‐ 37 ‐

×