IBM Developer WorksのDITAに関する記事

IBMのDeveloper Worksで興味深い記事が公開されました。

単一の DITA ソースから手順を説明するドキュメントと受け入れテスト用ドキュメントを作成する

DITA導入を検討している企業のドキュメント担当者には、とても参考になる記事だと思います。私が以前メーカーでマニュアル制作を担っていたころ、この記事で書かれているようなことを目指して、マニュアル制作にXMLを導入しました。

Developer Worksの記事の内容とは直接関係ありませんが、なぜ、マニュアル制作にDITAが有用なのか、私の考えていたことを書いてみます。

マニュアル制作を長年やっていて一番問題に思っていたのは、「製品開発の下流工程からマニュアル制作に取り掛かっても、良いマニュアルはできない」ということでした。

大切な情報がきちんと整理され、製品開発プロセスの始めから終わりまで、首尾一貫して維持管理されている

このことがとても大切だと考えていました。

製品開発の始まりには要件定義があって、それに基づいて機能設計が行われ、詳細設計へと進みます。要件定義の段階では、ユーザーの視点で「何ができるのか」、「どんなメリットがあるのか」を明らかにします。機能仕様書が完成すると、開発者は「どうやって作るか」に没頭するあまり、製品開発の目的を見失ってしまうことがしばしばあります。そのような開発者から情報をもらってマニュアル制作を始めたところで、良いマニュアルができるわけがありません。製品開発の下流工程になって、マニュアル制作担当者が要件定義に立ち戻ろうとしても、製品リリースのデッドラインが近づく中、悠長なことをやっている暇はありません。

テクニカルライティングを一生懸命学んでも、上記のような状況を打破することはできません。もちろん、良いマニュアルを作るのにテクニカルライティングは重要ですが、それだけでは解決できない大きな問題があるというのが現実です。

ポイントになるのは、

マニュアル制作担当者が製品開発の上流工程から関わることが、開発者にとってのメリットになる

ことではないかと考えています。

もし、マニュアル制作担当者が、

製品に関わる情報を体系化し、開発者をはじめとする関係者に分かりやすく見せる

ことができれば、これは開発者にとって大きなメリットになるのではないでしょうか。これがそんなに簡単なことだとは思っていません。以前、私がメーカーでマニュアルを作っていた頃は、こんなことをやりたいと思っても、それを実現する手段やツールを持ち合わせていませんでした。

少し話が逸れますが、ソフトウェア開発の世界では、構造化プログラミングからオブジェクト指向プログラミングへ移行するとき、仕事のやり方が大きく変わりました。オブジェクト指向では、各オブジェクトを独立して設計します。このため、オブジェクト指向設計は、大規模なソフトウェアを多くのエンジニアでコンカレントに開発するのに向いています。ただし、良いオブジェクト指向設計を行うには、各オブジェクトの役割やオブジェクト間の関係を明確にすることが重要です。この作業を行うのに、通常、UML(Unified Modeling Language)モデルが使われます。各オブジェクトの役割やオブジェクト間の関係を図にすることにより、設計思想が分かりやすくなり、レビューの質も向上します。オブジェクト設計が完了したら、UMLモデルからソースコードのひな形が生成され、プログラマーのコーディングが始まります。

何が言いたいかと言うと、良いマニュアルを作るのにオブジェクト指向設計と同じようなアプローチが取れるのではないか、ということです。そして、DITAはそのようなアプローチを取るために必要なものを提供してくれます。DITAによるマニュアル制作では、UMLモデルがDITAマップにあたります。DITAマップを使って、各情報(トピック)の役割や情報(トピック)間の関係を明確にします。こう考えると、DITAの肝はマップにあると言えます。

しかし、Developer Worksの日本語、用語が不適切なのが気になりました (^_^;)
DITAコンソーシアムジャパンでDITAの用語集を作成していると聞きました。
がんばって欲しいものです。