DITA の特殊化と拡張により、ユース・ケース・ドキュメントを作成する

Darwin Information Typing Architecture を使用して単一のソースからユース・ケース・ドキュメントを作成する

要件の収集とドキュメント作成とを組み合わせ、それを開発マネージャー、開発者、テスター、テクニカル・ライターが開発サイクル全体にわたって活用できるようにする方法を学びましょう。DITA (Darwin Information Typing Architecture) の柔軟な拡張メカニズムは、この種の作業の業界標準になりつつあります。この記事では、ユース・ケース・ドキュメントを作成するための特殊化されたスキーマを作成します。

Piers Michael Hollott, Senior Consultant, Sierra Systems

Piers Hollott はソフトウェア業界で 15 年間働いており、Java 開発、XML 技術、関数型プログラミングを専門としています。彼はいくつかのオープンソース・プロジェクトに貢献した経験があり、現在は Sierra Systems のコンサルタントをしています。



2011年 4月 19日

よく使われる頭文字語

  • DTD: Document Type Definition
  • OASIS: Organization for the Advancement of Structured Information Standards
  • PDF: Portable Document Format
  • XSD: XML Schema Definition
  • XML: Extensible Markup Language
  • XSL: Extensible Stylesheet Language

ソフトウェア業界では、ソフトウェア・アプリケーションとユーザーとのやりとりに関する情報を収集するために、ユース・ケースが使われます。OASIS の DITA (Darwin Information Typing Architecture) は XML ベースの技術ドキュメントを作成するためのフレームワークであり、指定のトピックに対する情報のマッピングと公開に使用されます。DITA では、1 つのトピックは 1 つの情報単位を表し、関連するトピック同士がトピック・マップを使って関連付けられます。同様に、ユース・ケースは大きなプロセスの一部分を表現し、ユース・ケース・モデルがプロセスの全体を表現します。DITA による構造的な特殊化を使用すると、既存のトピック・タイプを新しいトピック・タイプに拡張できる一方、既存のツールとの互換性を維持することができます。この、DITA の構造的な特殊化を使用することで、DITA の基本的なトピック・タイプを拡張し、ユース・ケースの収集に活用することができます。

この記事は、以前に公開された developerWorks の記事である「単一の DITA ソースから手順を説明するドキュメントと受け入れテスト用ドキュメントを作成する」の続きです。前回の記事では、アプリケーションの使用方法に関する単純なドキュメントを受け入れテストの際の QA (品質保証) ドキュメントとして再利用する方法について説明しました。そこでは DITA の基本的なトピック・タイプを使用しましたが、今回の記事では、より堅牢な方法として、基本的なトピック・タイプを拡張し、特殊化された新しいタイプを作成する方法について説明します。ただし単一ソースと再利用のメリットを重視する点は今回も同じです。

ユース・ケースを管理する

ソフトウェア開発において、ユース・ケースは記述の対象となるシステムとユーザーとの間のやりとりの 1 単位を表しており、ユース・ケース・モデルの中で多くのユース・ケースが互いに関連付けられています。通常、ユース・ケースが詳細に記述されるのはソフトウェア・プロジェクトの要件フェーズにおいてです。十分詳細に記述されたユース・ケースは開発チームに渡され、開発される製品の仕様として使用されます。これらのユース・ケースは単なる青写真ではありません。ユース・ケースは契約でもあり、開発チームに渡された後、受け入れテストを行う社内、工場、およびユーザーのテスターへと渡され、開発されたソフトウェアがユース・ケース・モデルによって指定される当初の要件を満たすかどうかの検証が行われます。

ユース・ケース・ドキュメント自体は静的であり、ビジネス・アナリストから開発者へ、そしてテスターへと渡されます。ユース・ケース・ドキュメントのフォーマットそのものは変更されませんが、ソフトウェア開発ライフサイクル (Software Development Life Cycle: SDLC) のさまざまなフェーズで、ユース・ケース・ドキュメントの中にあるさまざまな情報が使用されます。

適切なユース・ケースでは、ビジネス要件の収集、ソフトウェアの作成、そして受け入れテストというループは閉じられます。ただし非常に順調な場合であっても、ビジネス要件収集、ソフトウェア作成、受け入れテストは、SDLC のフェーズとしてそれぞれ異なり、各フェーズでのユース・ケースの使い方も異なります。ソフトウェア・プロジェクトでは、先に進むために必要な種類の情報がユース・ケースに含まれていないことがわかった場合、最も良くてもコストがかかり、最悪の場合は悲惨な結果となる可能性があります。

私がソフトウェア開発プロジェクトを管理する場合、時間の大半は「ドキュメントに含める内容を検討する」作業に費やされ、この作業によってユース・ケースなどのドキュメント作成の体系化や準備が行われます。他の記事で私が指摘したように (「参考文献」のリンクを参照)、こうした作業に対して柔軟な手法が求められています。


DTD と XSD を使用して DITA を定義する

先ほど触れたように、DITA はドキュメント化された各トピックを個別に表現する XML ベースのドキュメント作成フレームワークです。例えばマニュアルは、さまざまなタスクを実行する方法を記述した、いくつかのトピックで構成されています。そしてこれらのトピックがトピック・マップという XML 文書によって互いに関連付けられています。基本的なトピック・マップとトピックに加え、DITA フレームワークはさまざまなタイプのドキュメント作成に適するように特殊化されたトピック一式を提供できるように拡張されています。特殊化された基本的なトピック・タイプは、概念 (concept)、参照 (reference)、タスク (task) です。

DITA のドキュメントは DTD または XSD を使用して定義することができます。DTD と XSD はどちらも DITA Open Toolkit の一部として提供されており、多くの XML エディターで DTD と XSD を操作することができます。私は XSD スキーマを使用する方が好きですが、どのスキーマ言語を選択するかは皆さん次第です。どのスキーマを使用するにせよ、DITA トピック・タイプのスキーマの定義は 2 つの主な部分で構成されています。1 つはスキーマそのもの (例えば concept.dtd や reference.xsd など) であり、上位レベルのドメインのトピック・タイプを定義します。もう 1 つはモジュール (concept.mod や referenceMod.xsd など) であり、そのスキーマを構成する要素と属性を定義します。XSD スキーマを使用する場合には、定義される各 DITA 要素に対するプレースホルダーとしての xs:group 要素を含むグループ (referenceGrp.xsd など) も変更します。構造的な特殊化では、スキーマの定義、モジュール、グループ・ファイルを作成します。

一般的なトピック・タイプは 3 つの基本的なトピック・タイプに特殊化することができます。そのためには各トピック・タイプに対して新しいスキーマを作成し、そのトピック・タイプのすべての新しい要素と、新しいスキーマと元のスキーマとの関係を定義します。この関係を記述するためにはクラス属性を使用します。クラス属性については、以降でかなり詳しく説明します。ただし特殊化のプロセスは必ずしもこれで終わりではありません。同じプロセスを使用することで、3 つの基本的なトピック・タイプを特殊化して新しい DITA トピック・タイプを作成することもできるからです。このように DITA の構造的な特殊化を使用して DITA を拡張し、ユース・ケースの領域に活用することができます。

リスト 1 は基本的なタイプのタスクの DITA スキーマから引用したものですが、これを見るとデフォルトのクラス・ストリングである tasktaskbody がハイフン (-) で始まっていることがわかります。ハイフンは、この特殊化が構造的なものであることを示します。ハイフンの後に、トピック・タイプとトピック要素のペアがスラッシュ (/) で区切られ、その各ペアがスペースで区切られて続いています。このペア・リストによって新しい要素を定義し、その新しい要素をより汎用的な要素にマッピングしています。例えば taskbody は、taskbody よりも汎用的な body にマッピングされています。

リスト 1. task.class は topic.class から継承される
<!-- Base type: topic.class -->
<xs:complexType name="task.class">
     ...
     <xs:attribute ref="class" default="- topic/topic task/task "/>
</xs:complexType>

<!-- Base type: body.class -->
<xs:complexType name="taskbody.class">
     ...
     <xs:attribute ref="class" default="- topic/body  task/taskbody "/>
</xs:complexType>

DITA Open Toolkit

DITA Open Toolkit (「参考文献」を参照) は、さまざまなタイプの出力 (PDF など) を DITA ソースから生成できるオープンソースのプロジェクトです。構造的な特殊化では、いつでも新しい要素をより汎用的な要素にマッピングすることができるため、基本的なトピック・タイプを使用して作成された新しいトピック・タイプは、基本的なトピック・タイプのスタイルと、元の topic スキーマに関連するトピック・タイプのスタイルを継承しています。


DITA を使用してユース・ケースを詳細に記述する

私が前回寄稿した記事の場合と同様、ここで紹介するサンプル・アプリケーションは、あくまでも説明用のものです。このサンプル・アプリケーションは、ホーム・ページ、メイン・フロー (「順調な場合のパス」)、そして代替フローで構成される単純なウィザードに対する要件を記述しています。2 つのアクター (アプリケーションのユーザーとシステム) の間のメインのやりとりでは、ユーザーは自分の名前を入力するのに続いて、個人情報の詳細を変更することができます。

前回と同様、このアプリケーションはいくつかのページを含む 1 つのモジュールで構成されています。reference トピックに関する DITA トピック・マップにより、関連するユース・ケースに対し、これらのページを記述します。DITA トピック・マップはユース・ケース・モデルの役割を果たします。前回は task トピックを使用しました。今度は構造的な特殊化を使用して task トピックを拡張し、case という新しいトピック・タイプを作成します。

制約と不変状態

ユース・ケースは通常、ユース・ケースがトリガーされたときと完了したときにソフトウェアの状態を記述する、一連の事前条件と事後条件で構成されています。また、不変状態を定義することもできます。不変状態はルールと似ており、例えば「画面上に表示される苗字は必ず大文字にする」のように、ユース・ケース全体をとおして変化することはありません。DITA 特殊化を使用すると (多くの場合は concept トピック・タイプを継承することで)、これらの制約、条件、不変状態を独立にモデル化することができます。ここでは単純にするために、これらの詳細を case トピック・スキーマの本体に直接追加することにしました。

基本的な task トピックは DITA アーキテクチャーの一部として標準的に定義されており、前提条件、事後条件、そして (先ほど定義した不変状態と似た) コンテキストのための要素を含んでいます。これらの要素はすべて、基本的なトピックのセクション見出しクラスから継承されているため、1 つの見出し要素が複数の段落を含むことができます。ユース・ケース・トピックの場合、これらの要素 (またはこれらの要素を継承する類似の要素) に番号なしのルール・リストを使える必要があります。そうした方が、エミュレートの対象となる機能に近いからです。それを実現するためには、3 つのカテゴリーすべてにおいて、セクション・ヘッダーではなく、DITA の番号なしリスト要素を継承します。

リスト 2 は、DITA の基本的な番号なしリスト (ul) 要素とリスト項目 (li) 要素を継承して新しい要素を作成し、事前条件や制約の集合を表現する方法を示しています。ここで、constraints クラスを基本的なトピックの ul 要素にマッピングしているだけではなく、中間的なタスクの prereq 要素にもマッピングしていることに注意してください。ここではタスク/前提条件をケース/制約で置き換えているので、両方の祖先からスタイルを継承しようとしています。constraint 要素には中間的な祖先はありません。この特殊化の結果として、task トピックには 1 つの前提条件しかありませんが、case トピックには前提となる制約のリストが必要です。

リスト 2. caseMod.xsd の constraints クラス
<!-- Base type: ul.class -->
<xs:complexType name="constraints.class">
     <xs:choice maxOccurs="unbounded">
          <xs:group ref="constraint"/>
     </xs:choice>
     ...
     <xs:attribute ref="class" default="- topic/ul task/prereq case/constraints "/>
</xs:complexType>

<!-- Base type: li.class -->
<xs:complexType name="constraint.class" mixed="true">
     <xs:choice minOccurs="0" maxOccurs="unbounded">
          <xs:group ref="listitem.cnt"/>
     </xs:choice>
     ...
     <xs:attribute ref="class" default="- topic/li case/constraint "/>
</xs:complexType>

この記事のサンプル・ファイル (「ダウンロード」を参照) を見るとわかるように、事後条件と不変状態も同じような方法で定義されています。それぞれのケースで、task トピック・スキーマの要素は (セクション見出し (prereqpostreqcontext) としてスタイルが定義されましたが)、制約、条件、不変状態の番号なしリストによって置き換えられています。この方法でユース・ケースをモデル化しようとすると、これよりも複雑になりますが、この方法によって case トピックに汎用の task を継承させることができます。

リスト 3 のコードはスキーマ・グループ・ファイルの中に constraint グループが設定される様子を示しています。

リスト 3. caseGrp.xsd の constraint グループ
<xs:group name="constraints">
     <xs:sequence>
          <xs:element ref="constraints"/>
     </xs:sequence>
</xs:group>
<xs:group name="constraint">
     <xs:sequence>
          <xs:element ref="constraint"/>
     </xs:sequence>
</xs:group>

シナリオ、ステップ、やりとり

どのようなユース・ケースであれ、そのユース・ケースの中心には、ソフトウェアのユーザーとソフトウェアそのもの (多くの場合はシステムと呼ばれます) との間のやりとりがあります。ユース・ケースにはこのやりとりとアクターが数多く含まれる場合があり、広い意味では、これらの項目を DITA の reference トピックを使って記述する必要があります。参照は通常、実際のオブジェクトを表現するために使われるので、アプリケーションのユーザー、モジュール、ページを表現するには元々適しています。この場合も簡単のために、これらの参照の多くを case トピックの本体の中で表現することにしました。ただし、ユース・ケース・モデルを表現するためのトピック・マップからこれらの参照を別々に参照し、それらの参照を個々のユース・ケース・トピックに結び付けることもできます。しかし残念ながら、この記事ではその方法については説明しません。

DITA タスクの核心は一連のステップであり、これらのステップは番号付きリスト・クラス ol.class へと汎化することができます。ol.class クラスは皆さんが生成しようとしているモデルと似ていますが、重要な制限が 1 つある点が異なります。それは、step がその定義からしてアクターの属性ではないことです。この違いは重要です。というのも、ユース・ケース・シナリオの各ステップはアクターの属性でなければならないからです。多くの場合、ユース・ケースを定義する一連のステップは、アプリケーションのユーザーとシステムとの間でのやりとりを表現しています。他のアクターが関係するかもしれませんが、ユーザーとシステムというように単純化しても、とりあえず問題はありません。しかし step 要素はそうはいきません。また、DITA の標準的な task トピックには 1 つのステップ・セットしか含めることができませんが、ユース・ケースにはメイン・フローのみならず、代替フローもいくつか含められるようにする必要があります。

リスト 4 を見ると、ステップのクラスが継承され、継承元のクラスと似た scenario.class が作成されていることがわかります。特殊化されたクラスには、メイン・フローなのか代替フローなのかを記述するための属性が必要で、デフォルトでメイン・フローに設定されている必要があります。こうした複数のフローに対する処理はスキーマの別の場所で casebody 要素が定義されるときに行われます。タスクの本体では 1 つのステップ・セットとしてしかタスクを実行することができないため、ユース・ケースを使用することで、複数の代替ステップ・セットとしてユース・ケースを実行できるようになります。

リスト 4. caseMod.xsd の scenario.class
<!-- Base type: ol.class -->
<xs:complexType name="scenario.class">
     <xs:choice>>
          <xs:group ref="interaction" maxOccurs="unbounded"/>
     </xs:choice>
     <xs:attribute name="type" default="main">
          <xs:simpleType>
               <xs:restriction base="xs:string">
                    <xs:enumeration value="main"/>
                    <xs:enumeration value="alternate"/>
               </xs:restriction>
          </xs:simpleType>
     </xs:attribute>
     <xs:attribute ref="class" default="- topic/ol task/steps case/scenario "/>
</xs:complexType>

リスト 4 を見ると、新しい scenario 要素が stepsol の両方から継承していることもわかります。このように継承することで、新しい scenario 要素は DITA Open Toolkit などの DITA アプリケーションに遭遇した場合、継承元の要素と同じように動作する一方、新しい機能も相変わらずカプセル化しています。

リスト 5 はユース・ケースの interaction 要素を定義するクラスを示しています。この要素も特殊化の元となった step クラスと似ていますが、この新しい要素がアクターの属性でなければならない点が異なります。この場合はアクター・セットを「system」と「user」に制限しましたが、さらに他のアクターを追加し、それらのアクターで別のトピックを参照することもできます (この点についても、この記事では説明しません)。

リスト 5. caseMod.xsd の interaction.class
<!-- Base type: li.class -->
<xs:complexType name="interaction.class">
     <xs:sequence>
          <xs:group ref="cmd"/>
          ...
     </xs:sequence>
     <xs:attribute name="actor" default="system">
          <xs:simpleType>
               <xs:restriction base="xs:string">
                    <xs:enumeration value="user"/>
                    <xs:enumeration value="system"/>
               </xs:restriction>
          </xs:simpleType>
     </xs:attribute>
     <xs:attribute ref="class" default="- topic/li task/step case/interaction "/>
</xs:complexType>

これを見ても、この新しい要素が task トピックの継承元と DITA 基本トピックの継承元に基づいており、その両方から動作を継承していることがわかります。


全体を結合する

これで DITA の基本トピックの 1 つを拡張できたので、適当な XML エディターを使用して新しいユース・ケースを簡単に作成することや、新しいスキーマに基づいて、そのユース・ケースに内容を追加することができます。それを終えたら、この DITA トピックや他の DITA トピックを参照するトピック・マップを作成し、ユース・ケース・モデルとして使用することや、そのトピック・マップから DITA Open Toolkit を使用して PDF 文書を生成することができます。この方法により、DITA で利用可能になりつつある協調的な作成環境を活用できることを理解できると思います。また、要件を記述したドキュメントを XSL や XQuery の変換機能を活用して再利用し、ソフトウェア開発チームのさまざまなメンバーに役立つものにできることも理解できると思います。リスト 6 はサンプルの case ドキュメントです。

リスト 6. dita/case.xsd を使って作成されたユース・ケース・ファイル
<case id="UC5" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xsi:noNamespaceSchemaLocation="Schemas\dita\case.xsd">
     <title>Use Case 5: Review personal information</title>
     <casebody>
          <constraints>
               <constraint>First and Last Name have been entered</constraint>
          </constraints>
          <invariants>
               <invariant>First Name is capitalized</invariant>
               <invariant>Last Name is capitalized</invariant>
          </invariants>
          <scenario type="main">
               <interaction actor="system">
                    <cmd>displays current First and Last Name</cmd>
               </interaction>
               <interaction actor="user">
                    <cmd>accepts current First and Last Name</cmd>
               </interaction>
          </scenario>
          <scenario type="alternate">
               <interaction actor="user">
                    <cmd>rejects current First Name</cmd>
                    <stepresult>loads edit screen for First Name</stepresult>
               </interaction>
          </scenario>
          <scenario type="alternate">
               <interaction actor="user">
                    <cmd>rejects current Last Name</cmd>
                    <stepresult>loads edit screen for Last Name</stepresult>
               </interaction>
          </scenario>
          <conditions>
               <condition>returns to home page</condition>
          </conditions>
     </casebody>
</case>

まとめ

DITA フレームワークを使用することで、ソフトウェア・アプリケーションとユーザーとのやりとりをドキュメント化することができます。同様に、ソフトウェアのユース・ケースを使用することで、ソフトウェア・アプリケーションとユーザーとのやりとりの情報を収集することができます。つまり、DITA フレームワークとユース・ケースの相性が良いのは当然のことなのです。DITA の構造的な特殊化を使用して既存のトピック・タイプを拡張することで、ユース・ケース収集に役立つ新しいトピック・タイプを作成することができ、しかも既存のツールとの互換性は維持されるため、既存のツールを活用することができます。DITA の基本的なタスク・トピックを拡張すると、この新しいスキーマを使用して新しいユース・ケースを作成することができ、作成されたユース・ケースから、柔軟で保守が容易なユース・ケース・モデルを作成することができます。


ダウンロード

内容ファイル名サイズ
Sample files for this articleexamplecode.zip21KB

参考文献

学ぶために

製品や技術を入手するために

議論するために

コメント

developerWorks: サイン・イン

必須フィールドは(*)で示されます。


IBM ID が必要ですか?
IBM IDをお忘れですか?


パスワードをお忘れですか?
パスワードの変更

「送信する」をクリックすることにより、お客様は developerWorks のご使用条件に同意したことになります。 ご使用条件を読む

 


お客様が developerWorks に初めてサインインすると、お客様のプロフィールが作成されます。会社名を非表示とする選択を行わない限り、プロフィール内の情報(名前、国/地域や会社名)は公開され、投稿するコンテンツと一緒に表示されますが、いつでもこれらの情報を更新できます。

送信されたすべての情報は安全です。

ディスプレイ・ネームを選択してください



developerWorks に初めてサインインするとプロフィールが作成されますので、その際にディスプレイ・ネームを選択する必要があります。ディスプレイ・ネームは、お客様が developerWorks に投稿するコンテンツと一緒に表示されます。

ディスプレイ・ネームは、3文字から31文字の範囲で指定し、かつ developerWorks コミュニティーでユニークである必要があります。また、プライバシー上の理由でお客様の電子メール・アドレスは使用しないでください。

必須フィールドは(*)で示されます。

3文字から31文字の範囲で指定し

「送信する」をクリックすることにより、お客様は developerWorks のご使用条件に同意したことになります。 ご使用条件を読む

 


送信されたすべての情報は安全です。


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=60
Zone=XML
ArticleID=660416
ArticleTitle=DITA の特殊化と拡張により、ユース・ケース・ドキュメントを作成する
publish-date=04192011