Ce diaporama a bien été signalé.
Nous utilisons votre profil LinkedIn et vos données d’activité pour vous proposer des publicités personnalisées et pertinentes. Vous pouvez changer vos préférences de publicités à tout moment.

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

6 654 vues

Publié le

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

Publié dans : Développement personnel
  • DOWNLOAD THIS BOOKS INTO AVAILABLE FORMAT (Unlimited) ......................................................................................................................... ......................................................................................................................... Download Full PDF EBOOK here { https://tinyurl.com/y6a5rkg5 } ......................................................................................................................... Download Full EPUB Ebook here { https://tinyurl.com/y6a5rkg5 } ......................................................................................................................... ACCESS WEBSITE for All Ebooks ......................................................................................................................... Download Full PDF EBOOK here { https://tinyurl.com/y6a5rkg5 } ......................................................................................................................... Download EPUB Ebook here { https://tinyurl.com/y6a5rkg5 } ......................................................................................................................... Download doc Ebook here { https://tinyurl.com/y6a5rkg5 } ......................................................................................................................... ......................................................................................................................... ......................................................................................................................... .............. Browse by Genre Available eBooks ......................................................................................................................... Art, Biography, Business, Chick Lit, Children's, Christian, Classics, Comics, Contemporary, Cookbooks, Crime, Ebooks, Fantasy, Fiction, Graphic Novels, Historical Fiction, History, Horror, Humor And Comedy, Manga, Memoir, Music, Mystery, Non Fiction, Paranormal, Philosophy, Poetry, Psychology, Religion, Romance, Science, Science Fiction, Self Help, Suspense, Spirituality, Sports, Thriller, Travel, Young Adult,
       Répondre 
    Voulez-vous vraiment ?  Oui  Non
    Votre message apparaîtra ici

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 ‐

×