Mr.DITA Japan Blog 2015/3

<<前へ

DITA Festa2015 Kyoto

[会社] 投稿日時:2015/03/23(月) 09:38

先週の金曜日、京都にてDITAコンソーシアムジャパンの「DITA Festa2015 Kyoto」に参加致しました。

15分のソリューションマラソン枠、プレゼンの達人さんの後を引き継いでということで、デモでも加えて固めの事業紹介的な内容を広げる準備をしてきましたが、やはり時間が短くデモのタイトルだけに終わってしまいました。どうも営業的なプレゼンは性に合いません。

とは言え、これまであまり公に語ることの無かった現場のベテランとしての来歴(実務経歴)、他社のコンサルサービスとの違い、サービス、ソリューション、新規の告知などは枠内でできました。

まとめると、

  1. ストラクチャードコンテンツには、独立前の会社から20年実務に関わっているベテランのマイクロファーム
  2. インフォパースをハブ(ワンストップ)の窓口とする協業のビジネス
  3. 導入調査から運用後の改善までコンテンツライフサイクル全般を支援
  4. 制作業務の支援がサービスの中核であり、当事者意識が欠如しているコンサル型とは異なる実践型ハイブリッドサービス
  5. JDIGとしてはDITA導入コンサルもおこなっている(専門性をもった3社)
  6. 国内DITA導入成功事例の2社の導入に長期にコンサルとして関わって独立
    日経ビジネスONLINEでのDITA導入企業2社の紹介記事は、弊社から記者への紹介
  7. DITA研修サービスでは、Mr.DITA Eliot Kimber氏と「DITA Dojo」教育カリキュラムを計画中
    DITA for Small Teamsを最初のワークショップとして準備(国内向け)
  8. 会員制のDITA CCMSレビュー記事を開始
    第一弾は、ドイツのクラウド型 CCMSソリューション「DITAworks」の予定

Smart'n'Readyは、XDocs DITA CCMSをベースとした、oXygen、FrameMaker(DITA-FMx)、Word(Content Mapper)の循環ソリューションを簡単にデモする予定でした。近日中にウェビナーなどでoXygenとContent Mappperの校閲プロセスにおける循環ソリューションについてご紹介いたします。ご期待ください。

コンテンツ管理システム

[DITAスタイルガイド] 投稿日時:2015/03/11(水) 19:29

コンテンツ管理システム(CMS)とは、作成、更新、パブリッシング、および情報の翻訳のプロセスを含めた文書開発ライフサイクルを管理するためのソフトウェアシステムです。CMSは、DITAのような、モジュール化された文書化手法では、特に重要となります。なぜなら、執筆者に既に書かれたトピックや要素を探し出させたり、相互参照や他の関連リンクを壊すこと無くファイルやフォルダーの名前を管理したり、コンテンツ参照を管理したり、複数の執筆者が同一の文書に共同で作業したり、以前のバージョンのトピックをバックアップ、アーカイブや他のバージョンコントロールの目的のために格納したりすることができるようになるからです。

さらに、システムの多くでは、リリースの状態によって、ドラフトからレビューを経て、承認、リリースまでの進行過程を管理させることができます。大多数のシステムでは、ユーザー権限管理を含むことによって、ユーザーは個別に、文書化プロセスにおける役割ごとに、情報への異なるアクセス権を与えられます。

DITAプロジェクトにおいては、コンテンツ管理は共同作業が必須の場合は、より重要になります。仮に一人の人間がコンテンツ ライフ サイクルにおける6つの段階全てに責任を担っている場合は、コンテンツ管理のタスクは単純です。しかしながら、多数の執筆者、エディター、多くの言語、複雑な承認ルールや複雑なアーカイブ要件が存在する場合は、管理タスクは膨大なものとなり、CMSは必須要件となります。

CMSは、代表的なものとして、以下の機能をサポートします。

  • 文書とマルチメディア素材のインポートと作成。
  • 全てのキーとなるユーザーと役割の識別。
  • 異なるコンテンツのインスタンスに対してカテゴリーやタイプごとに役割や責任をアサインできる性能。
  • コンテンツの変更を希望するユーザーにアラートできる性能。
  • 一つのコンテンツの複数バージョンを追跡し、管理できる性能。
  • 全てのコンテンツに渡ってテキストやメタデータを検索できる性能。
  • コンテンツをパブリッシュできる性能。

CMSにおいてコンテンツは、一般的には、(DITA形式で)データベース リポジトリ内に格納されます。データベースは、複数のバージョンの管理やコンテンツの取得やアーカイブを容易にします。幾つかのシステムは、XMLファイルの扱いにoptimizedテータベース技術の一種であるXMLデータベースを利用しています。

このブログポストテーマでは、弊社で準備中のoXygenの状況依存スタイルガイド参照機能やトニー・セルフ著の「The DITA StyleGuide」出版前のドラフト日本語翻訳原稿をWork-in-Progressとして一部のコンテンツを抽出してアップしています。 oXygen状況依存ヘルプは、弊社にてoXygenライセンスをご購入のユーザー様にオプションサービスとして提供を予定しています。

DITAパブリッシング プロセス

[DITAスタイルガイド] 投稿日時:2015/03/11(水) 19:21

DITAコンテンツは、様々なツールで読み込むことができる出力形式にパブリッシュすることができます。パブリッシング ツール、もしくはDITAプロセッサーは、幾つかの異なるテクノロジーを利用しています。

大多数のプロセッサーは2つのキーとなるテクノロジーを使っています。

  • XSL-T
    DITAをHTML、DocBookなどのほかの異なるマークアップ言語に変換
  • XSL-FO
    DITAがPDFやRTFなどのページ レイアウト形式へ処理される際に、中間形式として使われるXMLフォーマッティング言語

プロセッサーは、DITAマップを解析、内容参照トランスクルージョン要素を解決、相互参照を解決、フォーマットにおけるラベル付けや番号付けの適用、DITA要素を出力形式要素へマッピングする、などの幾つかの処理をステップにわけておこなっています。

DITAパブリッシング プロセス DITAからPDFへの変換においてのツールと上流プロセスの概要を表示。

代表的なDITAからPDFへの変換の概要

このブログポストテーマでは、弊社で準備中のoXygenの状況依存スタイルガイド参照機能やトニー・セルフ著の「The DITA StyleGuide」出版前のドラフト日本語翻訳原稿をWork-in-Progressとして一部のコンテンツを抽出してアップしています。 oXygen状況依存ヘルプは、弊社にてoXygenライセンスをご購入のユーザー様にオプションサービスとして提供を予定しています。

ファイルとフォルダー名前付けの約束事

[DITAスタイルガイド] 投稿日時:2015/03/11(水) 18:46

記述的なフォルダーとファイル名を使ってください。.ditaをトピックファイルの拡張子として使い、.ditamapをDITAマップファイルに使ってください。ファイル名は大文字と小文字を区別し、小文字のファイル名が好ましい。情報タイプと呼応する文字を接頭辞とするトピック名としてください。

 

ファイルとフォルダー構造

理想的なDITAプロジェクトのファイル構造は、DITAマップを文書のリポジトリ フォルダーのルートレベルにもち、トピック コンテンツをルートから下がったサブフォルダーに格納する方法です。この構造は、コンテンツへのトピック参照 リンクがいつもツリー構造上で一段下がっているということを確実にします。DITAマップは、トピックの情報上位セットですので、DITAマップを上位フォルダーにもつのは論理的なアプローチです。

イメージや他のメディアリソースは、(/imagesなどの)分離されたフォルダーに格納されるべきです。

以下を含んだ幾つかのファイル トポロジーを利用できます。

  • 情報タイプ別(コンセプト、タスク、リファレンス)
  • 文書化されたシステムコンポーネント別(エンジン、燃料系統、など)
  • サブジェクトの範囲別(入門、借方での作業、など)

論理的で、コンテキスト非依存なトピックの格納場所を使うことは、後に、一つのプロジェクト フォルダーから別のプロジェクト フォルダーにファイルを移動させるときに発生する諸問題を低減できます。ファイルを見つけやすくもします。

出力ファイルを生成したい場所を決してベースの格納場所にしてはいけません。ファイルのある場所にコンテキストを持ち込むことになり、デリバリーにおいて、コンテンツとフォーマットの分離という基本原則を破ることになります。

何百ものトピックファイルをひとつのフォルダーに格納することになるフラットで浅いファイル構造を使うことを避けてください。この構造は、ファイルを開く ダイアログが、例えば、選択するのに、全てのファイルを列挙することが必要になり、DITAエディター上でのファイルの取得を結果として遅らせることになりかねません。

 

ファイル名

ファイルの名前を選ぶ際には、以下のガイドラインを守ってください。

  • 記述的で、短い名前、小文字を使う。
  • アルファベットと数字を組み合わせた文字を使う。
  • 略称よりも完全な単語を選ぶ。
  • 空白を使わない(単語の間には空白では無く下線を使う)。
  • 情報タイプを特定する文字(c、t、r)を初めにつけ、下線文字で分離されたものをファイル名とする。
  • 一貫性を保つ。

"Refreshing the cache"をタイトルとするタスク トピックのファイル名としての例は、t_refreshing_the_cache.ditaとなります。

記述的な名前の使用と下線による分離は、人による読みやすさと識別を高めることを目的としています。

 

ファイルとフォルダー名における大文字と小文字の区別

幾つかのツールや環境においては、ファイルとフォルダー名の大文字小文字識別が当たり前であったとしても、ファイルとフォルダー名の大文字小文字の区別については、完全に一貫していなければなりません。DITAのひとつの重要な側面は、互換性です。ファイル名の大文字小文字識別が一貫していないと、大文字小文字を識別する環境のユーザーとのドキュメント交換において問題を起こすかもしれません。

加えて、DITA ツールによっては、同じワークフロー(もしくはパイプライン)であっても、ファイル名の扱いが異なる場合があります。例えば、DITA オープンツールキットのパイプラインの一部で、次のステップに遷移する前に(abc.dita)ファイルが存在するかオペレーティング システム上でチェックするとします。オペレーティング システムは、ファイル名ABC.ditaのファイルが存在することで、yesと応答します。例え、大文字小文字識別で完全に一致した(abc.dita)が存在していなくてもです。次のステップ(case aware)が開始されると、ファイルabc.ditaを見つけることができず、クラッシュすることになるかもしれません。

ファイルとフォルダー名は、大文字小文字識別されるものとして扱ってください。

 

ファイル名に特殊文字を使うことは避ける

ファイルの名前に特殊文字を使うことは、特定のオーサリングやパブリッシング ツールに問題やエラーを起こすことがあります。この文脈における特殊文字とは、シンボル、印刷用文字、句読文字、空白、区別文字、非ラテン文字を意味しています。

ファイル名をURIであるかのように扱い、URL名前付けへのIETF構文の約束事に従うべきです。

より詳しいURIガイドラインについては、IETF 統一資源識別子(URI) 共通構文を参照してください。

 

DITAトピックとDITAマップの拡張子

ほとんどのDITAオーサリング ツールは、.ditaや.xmlファイル拡張子でトピックを保存することができます。

.ditaファイル拡張子を使うことを心がけてください。

.dita拡張子を使うべきなのは以下の理由からです。

  • DITA トピックをDITA オーサリング ツールに特定して関連付けることができます。汎用の拡張子.xmlのファイル名では、十分にファイルを識別できません(DITAかもしれませんし、他のXMLファイルかもしれません)。例えば、.dita拡張子を使えば、Windows OSで設定すれば、ダブルクリックするだけで、好みのDITAエディター上でファイルを開くことができます。
  • .dita拡張子あることがユニークであるため、フォルダーをブラウズするときに、DITAファイルを容易に認識することができます。
  • DITAプロセス内では、DITAトピックやDITAマップ以外でも、XMLファイル形式のものが存在します。例えば、XML ビルドファイルやDITAVAL ファイルです。.ditaをトピックに使えば、他の補助ファイルと区別することができます。

ほとんどのオーサリング ツールは、.ditamap拡張子や.xml拡張子でDITAマップを保存することができます。

DITAマップ ファイル(ブックマップも含む)には、.ditamap拡張子を使うことを心がけてください。

 

特殊化 要素と属性の名前付けにおける約束事

DITAスキーマが特定のドキュメンテーションの要件を満たすべく特殊化された場合、特殊化の開発者(specializer)は、要素と属性の名前を選ばなければいけません。

specializer にとっては、すべて小文字(buttonname)、小文字とハイフン(button-name)、 キャメルケース(ButtonName)、小文字でキャメルケース(buttonName)、加えて、ほかの変形も技術的には有効です。とは言っても、キャメルケースで最初の語句が小文字であるのが推奨のお約束事です。

基本は以下のとおり:

  • 識別のための接頭辞を要素名として使うべき。
  • 小文字ではじめて、それからキャメルケースの要素や属性名を使うべき。

それゆえ、先の例で最も推奨される名前は、hwButtonNameとなります。

基本DITAコンテンツモデルで既に使われているものは使うべきではありません。

接頭辞を使うことによって、特殊化された要素をより認識しやすくし、基本DITA名との名前衝突における危険性を回避することができます。

このブログポストテーマでは、弊社で準備中のoXygenの状況依存スタイルガイド参照機能やトニー・セルフ著の「The DITA StyleGuide」出版前のドラフト日本語翻訳原稿をWork-in-Progressとして一部のコンテンツを抽出してアップしています。 oXygen状況依存ヘルプは、弊社にてoXygenライセンスをご購入のユーザー様にオプションサービスとして提供を予定しています。

執筆者への制約と要素選択肢の制限

[DITAスタイルガイド] 投稿日時:2015/03/11(水) 18:31

執筆者によるセマンテック マークアップ要素選択時の負担を減らすために、選択時に選べる要素の数を減らすことができます。この制約は、オーサリング ツール、もしくはDITA 1.2で新たに機能として加わった制約メカニズムによって管理することができます。

オーサリング チームのなかには、チームの執筆者の使えるDITAの要素に制約を加えることを選んでいるところもあります。これはカジュアルな制約("してはいけません、さもないと!")か、(ソフトウェアによる)本式の制約であるかもしれません。

DITAオーサリング ツールのなかには、オーサリング インターフェース上で、表示される要素を制約したり、制限したりできる仕組みを提供しています。制約は、共通の主題のためにグループ化された要素である、マークアップ ドメインに基づき管理されるのが一般的です。

DITAマークアップ ドメインを表示させないためのオーサリング ツールのダイアログ ボックスの例

DITA 1.2から機能として加わった制約メカニズムは、執筆者に要素選択をより単純化して提供するための、制約のかかった情報タイプを作成する手法に、標準の方法を提供します。

このブログポストテーマでは、弊社で準備中のoXygenの状況依存スタイルガイド参照機能やトニー・セルフ著の「The DITA StyleGuide」出版前のドラフト日本語翻訳原稿をWork-in-Progressとして一部のコンテンツを抽出してアップしています。 oXygen状況依存ヘルプは、弊社にてoXygenライセンスをご購入のユーザー様にオプションサービスとして提供を予定しています。

«前へ