Zendeskの一般向け製品ドキュメントはすべて、このZendeskヘルプセンターで公開されています。Zendeskのほとんどのチームはヘルプセンターで直接コンテンツを作成していますが、ドキュメントチームはオフラインでDITAソースファイルを使用して製品ドキュメントを作成、管理しています。DITAとはDarwin Information Typing Architectureの略で、コンテンツを作成して公開するためにXMLを利用するデータモデルです。基本的に、DITAファイルはプレーンテキストのXMLファイルです。
この記事では、次のトピックについて説明します。
DITAを活用する理由
DITAは、大規模な文書セットを作成し、管理するための業界標準であり、1つのソースから複数のチャネルにコンテンツを公開するように設計されています。techwhirl.comのJacquie Samuels氏は、DITAが解決しようとしている問題を次のように説明しています。
Word、メール、PowerPoint、WordPress、HTML、InDesign、FrameMakerなどのフォーマットでコンテンツを書くのは、石版に文字を刻むようなものです。コンテンツは、本質的にそのフォーマットから抜け出せなくなり、処理しづらくなります。そのようなコンテンツは、ほかの目的で簡単に再利用することができず、非効率的でコストもかかります。
DITAは、資産として管理できるようにコンテンツを作成、保存する方法です。XML(eXtensible Markup Language)を利用して、コンテンツをインテリジェントで汎用性が高く、管理しやすく、移植性の高いものにすることができます。
たとえば、DITAで作成されたコンテンツは、PDF、HTML、RTF、PowerPoint、モバイル対応のフォーマットでブランド化して公開することができます。コンテンツをファイル間でコピー&ペーストすることはありません。
(出典:What Is DITA?、TechWhirl)
Zendesk DocsチームにとってのDITAのメリットは、コンテンツとフォーマットを分けられること以外にも、以下のようなものがあります。
- コンテンツの構造について規律を守らせることができる。DITAファイルはXMLであるため、構造が無効な場合、ツールで作業ができません。
- コンテンツの移動が簡単。トピックノードを構造体のある場所から別の場所にドラッグするだけです。
- 複数の記事のコンテンツを塊にしてインポートし、再利用することができる。
- PDF形式にする機会は少ないが、PDFで公開するときはDITAファイルをソースにできる。
Zendeskで使用しているDITAオーサリングツールはOxygen XML Authorです。堅固なオーサリング環境に加え、検索、検証、XHTML変換など、他の多くの機能を利用しています。他のDITAオーサリングツールとしては、Framemaker、Arbortext、XMetalなどがあります。
記事を作成して公開する方法
記事の執筆者はOxygen XML Authorを使用して、DITAファイル内のコンテンツを作成または更新します。DITAは1つのソースからマルチチャネルパブリッシングを可能にするために作成されたため、DITAテキストファイルにはスタイル設定が含まれていません。含まれるのは構造化されたコンテンツだけです。Webチャネルでは、すべてのスタイル設定はDITAではなく、外部のCSSスタイルシートによって提供されます。Zendeskでは、すべてのスタイル設定はGuideのテーマのスタイルシートによって提供されます。
公開の準備が完了したら(通常、製品機能のリリースや更新と同時に)、Authorを使ってDITAをXHTMLに変換します。XHTMLは、より厳密なバージョンのHTMLです。その後、ヘルプセンターAPIを使用してXHTMLをヘルプセンターに公開します。
バージョン24以降のOxygen XML Editorには、DITAトピックをXHTML出力にパブリッシュして、記事としてZendeskヘルプセンターに直接アップロードできる変換シナリオが組み込まれています。XML Editorのヘルプで「DITA Map Publishing」を参照してください。ビデオについては、XML Editorのヘルプで「Publishing Content to Zendesk Help Center」を参照してください。
時によって、大量の記事を短時間に更新しなければならないこともあるでしょう。例を挙げると、Zendeskでは、価格設定とブランディングをよりわかりやすく簡潔になるように変更した際、締め切り日の午前8時(太平洋標準時)までに何百件もの修正記事を公開しなければなりませんでした。締め切りまでの数週間、執筆者がDITAのソースファイルを更新し、ZendeskがAuthorを使ってファイルを一括変換しました。そして、それらのファイルをヘルプセンターAPIを使用してヘルプセンターに公開しました。修正記事の公開にかかった時間はわずか数分でした。
ファイルの管理方法
ZendeskではDITAファイルの管理にGitHubを使っています。記事を作成したり更新したりする前に、執筆者がリポジトリにブランチを作成して変更を加え、プルリクエストを作成します。プルリクエストは、チームの他の執筆者によってレビューされます。これには、執筆者にはお互いの記事をピアレビューする機会が与えられるという利点もあります。
Zendeskでは、アマゾンウェブサービス(AWS)が提供するスケーラブルなクラウドストレージサービスであるAmazon Simple Storage Service(Amazon S3)に画像を保存しています。記事中の画像はすべて、ヘルプセンターからではなく、S3からブラウザにダウンロードされます。Amazon S3サービスを利用することで、画像の管理がより簡単になります。
地域に密着した記事の公開
Zendeskヘルプセンターのデフォルトの言語は英語です。製品ドキュメントは、ドイツ語、スペイン語、フランス語、日本語、韓国語、ポルトガル語(ブラジル)、イタリア語、簡体中国語でも公開しています。
ローカリゼーションのためのハンドオフが必要な場合は、ヘルプセンターAPIを使用して選択した英文記事をヘルプセンターからダウンロードし、HTMLファイルに書き出します。Amazon AWS APIを使用して、Amazon S3バケットから記事の画像をダウンロードします。HTMLファイルと画像をパッケージ化して、ローカライゼーションベンダーに渡します。ローカライゼーションベンダーから翻訳が戻ってきたら、ヘルプセンターAPIとAmazon APIを使って記事と画像をアップロードします。