製品マニュアルの DITA 化と AH pdf5 による版面デザイン

背景

弊社は金融機関向けのアプリケーションを作成しているソフトウェアベンダーです。 製品とともに製品マニュアルを始めとした関連ドキュメントを作成します。 ドキュメントは現在のところ以下の4種類です。

• ユーザーマニュアル（アプリケーションの操作マニュアル）
• テクニカルマニュアル（アプリケーションの内部のロジック説明）
• インストールマニュアル（アプリケーションのインストール手順書）
• リリースノート

これらのドキュメントそれぞれに対して最大で以下のバリエーションが存在します。
製品別（4種類）×バージョン別×顧客別（10数社）×言語別（日・英）

今回、これまでに作成されたドキュメントのうちDITA化し、AH pdf5 を用いてPDF化したのは、“ユーザーマニュアル”です（対象製品、バージョン、顧客は1種類。言語は日・英）。

これまでのマニュアル作成

• LaTeXによるマニュアル作成

  弊社の設立から2001年まではマニュアルはMicrosoft社のワードプロセッサーMS-Wordを用いて作成していました。2001年以降、製品数の増大、各顧客からの新機能の要求に伴いアプリケーションのロジックが複雑化していきました。内部仕様を正確に記すためテクニカルマニュアルの拡充が急がれ、大量の数式を含むドキュメント作成が必要となるためLaTeXを採用しました。 ユーザーズマニュアル等その他のドキュメントも同じくLaTeXによって作成していました。

• 脱LaTeX

  LaTeXが吐き出すドキュメントの美しさには大いに魅力を感じますが、近年以下の理由からLaTeXによるマニュアル作成に限界を感じ始めました。

  • 習得の壁：独自の言語なので、使いこなすにはかなりの習熟が必要。
  • ソース管理：再利用や条件コンパイルが難しい。
  • 形式の制限の緩さ：ソースの記述の制限が緩いため、出来上がりのドキュメントのテイストが均一にならない。

  こうしたテクニカルな問題点に加え、人材の問題もあります。テクニカルライターを募集したところで、なかなかLaTeXが使える人は集まりません。弊社の海外オフィスでテクニカルライターを募集したところ、Adobe社のドキュメント作成アプリケーションFramemakerの経験者が散見されました。そこで脱LaTeXの第1歩としてFramemakerを試しました。 ところが、以下のような問題が発生しました。

  • 習得の壁：操作解説の書籍がほぼ皆無。ネット上のリソースがたより（LaTeXより難しいのではないか！？）。
  • 重い：GUIを備えたアプリケーションなので、かなりのマシンパワーを要する。
  • 日本語対応の問題：もともとが欧米言語用のアプリケーションで、日本語へのローカライズが不十分。

  これらのテクニカルな問題に加えて、やはり気になるのが将来性。あまりにアプリケーションに依存した環境でコンテンツ作成から出力まで行うと、アプリケーションのバージョンアップに際して、コンテンツやレイアウトに不具合が生じる可能性もあります。更に言うと、Framemaker自体が生産終了・サポート切れとなった場合にそれまでに作成したコンテンツがすべて使えなくなる危険性すらあります。

そしてDITAへ

Framemaker単体でマニュアル執筆から、今後の展開を考えXMLでのコンテンツ作成に転換したのが2011年6月。ここで初めてXMLドキュメンテーションの方法論としての“DITA”の存在を知りました。ライターの要望であくまでFramemakerの使用に拘ったために、Framemaker用のDITA作成支援のプラグインを使用して1ヶ月ほど試行錯誤を繰り返しましたが、生産性の向上が望めず2011年7月にFramemakerの使用を放棄、執筆環境をAdobe社のFramemakerからSyncroSoft社のoXygenに変更し、ビルド環境もDITA-OTを使うことにしました。
Framemakerにおける問題点のほとんどは日本語ドキュメント作成に関するものでした。残念なことにDITA-OTの標準のビルドで作成される日本語版PDFもそのままでは全く鑑賞に堪えるものではありません。結局どうしても立ちはだかる問題は日本語PDFの作成です。
そんな時、日本語XML組版の実績のあるアンテナハウスの“pdf5”なるスタイルを知りました。日本語の版面に特化したpdf5はそのままでもこれまで見た中では最高品質の日本語PDFが出力されましたが、まだ満足いくものではありませんでした。そこでアンテナハウスに版面デザイン（pdf5の改良）を依頼しました。 以後は、トピック執筆と版面デザインを並行して進め、2011年の9月末にマニュアルが完成しました。

• 版面デザインについて

  Framemakerはやはりテクニカルドキュメント作成に関しては確固たる実績を持っているので、少なくとも英語版の版面のデザインは標準的なものでした。そこでpdf5の改良に関してはフォント、扉のデザイン、柱の幅、ヘッダー・フッター、相互参照の形式、目次のデザイン、索引のデザインといったベースの版面デザインはFramemakerのそれをできるだけ真似るよう依頼しました。並行してライターから様々な要望や不具合の報告があるたびに、アンテナハウスに対応していただきました。

  工夫の1例を以下に挙げます。

  • ボイラープレートグラフィクス：< note >タグをつけるとtype属性に応じたアイコンを柱に表示するようにました。
  • 箇条書きの拡張：<ol>タグのoutputclass属性を利用して、異なる形式の箇条書きを表示します。
  • 数式対応：MathMLを用いた数式の表示、相互参照に対応。

今後の作業と課題

現状では1つのドキュメントをDITA化したに過ぎません。つまりDITAの最大の特徴である「再利用性」はまだ活用しておりません。
次の一手としては他の製品のユーザーマニュアルを作成する予定です。ほとんどのトピックは再利用が可能なはずなので、conrefのソースを入れ替えるだけでほぼ完成するのでは、と予想しています。
こうして先ずは同一のドキュメント（ユーザーマニュアル）の他のバージョン（つまり製品別、バージョン別、顧客別）を作成することでコンテンツの整理、conrefソースの充実を図ります。そうすることでDITAの利点を活用するノウハウを蓄積し、他のドキュメントのDITA化に役立てます。
他のドキュメント作成に際しては、アンテナハウスに版面デザインを依頼することになります。また他のドキュメントのDITA化に際しては、もしかしたら特殊化が必要になるかも知れませんので、その対応もお願いすることになるでしょう。

アンテナハウスへの要望

今回作成していただいたユーザーマニュアルの版面デザインに関して言うと、英語版はほぼ期待通りのものとなりましたが、日本語版はまだ100%満足いくものではありません。
以下に主な改善希望点を列挙します。

• 柔軟な詰め：一文字だけ行頭にいってしまう、ということのないように柔軟に詰めを調整してほしい。
• XMLの改行処理：XMLの仕様として改行は半角スペースになるそうですが、日本語の場合これは不要な処理です。

これらの要望とは別に、エンドユーザーでも簡単に行送りや柱の幅、フォントなどを指定できるようなGUIを備えたスタイルシート編集ツールを切望します。