![Close [x]](http://dw1.s81c.com/i/c.gif){kind=small}
In the software industry, use cases are used to gather information about how a software application interacts with its users. The OASIS Darwin Information Typing Architecture (DITA) is an XML-based technical documentation framework used to map and then publish information on a given topic. In DITA, a single topic represents a unit of information, with related topics associated with one another using a topic map. Similarly, a use case represents a single piece of the larger process, with a use case model representing the entirety. Using DITA structural specialization, which extends existing topic types into new ones while maintaining compatibility with existing tooling, you can extend the basic DITA topic types to support use case gathering.
This article continues from a previous developerWorks article, Create walk-through and acceptance scripts with single-sourced DITA, that described how to re-purpose a simple usage document for use as a quality assurance (QA) document during acceptance testing. Whereas the previous article uses the basic DITA topic types, this article takes the more robust approach of extending the basic topic types into new specialized types while maintaining an emphasis on the benefits of single-sourcing and re-purposing.
In software development, a use case represents a discrete unit of interaction between a user and the system being described. Many use cases are related to each other in a use case model. Typically, use cases are elaborated on during the requirements phase of a software project. After use cases have been sufficiently elaborated on, they are delivered to the development team, which uses them as a specification for the developed product. These use cases are not just a blueprint. They are also a contract, which is then subsequently delivered to in-house, factory, and user acceptance testers, who verify that the developed software fulfills the original requirements that the use case model provided.
A use case document in itself is static, passed from business analysts to developers and testers. The format of the document itself does not change—although different pieces of information in the document are used during different phases of the software development life cycle (SDLC).
A good use case closes the loop between business requirement gathering, software construction, and acceptance testing. At the best of times, however, these are different phases of the SDLC, and the way a use case is used during each of these phases is bound to be different. In a software project, discovering that a use case does not contain the necessary categories of information to move forward can be at best costly—at worst, disastrous.
When I manage software development projects, much of my time is spent on "content wrangling" that organizes and prepares documentation such as use cases. As I have pointed out elsewhere (see Resources for a link), a more flexible approach is timely.
As mentioned, DITA is an XML-based documentation framework that represents each
documented topic separately. For instance, a manual might consist of a number of
topics describing how to perform a variety of tasks. These topics are then related
to one another by an XML document called a topic map. In addition to
the basic topic map and topic, the DITA framework has been extended to provide an
assortment of more specialized topics that are appropriate for different types of
documentation. The basic specialized topic types are concept,
reference, and task.
You can define DITA documents using either a DTD or XSD. Both are provided as part of
the DITA Open Toolkit and are readily available with many XML editors. I prefer to
use the XSD schemas, but the choice of schema language is up to you.
In either case, the schema definition for a DITA topic type consists of two main pieces:
the schema itself (for example, concept.dtd or reference.xsd), which defines the
high-level domain of the topic type, and the module (for example, concept.mod or
referenceMod.xsd), which defines the elements and attributes that make up the
schema. If you are using XSD schemas, you also modify a group (such as
referenceGrp.xsd), which includes placeholder xs:group
elements for each DITA element defined. Structural specialization involves creation
of the schema definition, module, and group files.
The general topic type is specialized into the three basic topic types by the creation of a new schema for each, defining all new elements in the topic type and how the new schema relates to the original. You use a class attribute, described in greater detail in the text that follows, to describe this relationship. The process of specialization need not end there, however, as the three basic topic types can in turn be specialized to create new DITA topic types using the same process. In this way, you can use DITA structural specialization to extend DITA into the use case domain.
In Listing 1, taken from the DITA schema for the basic task type,
you can see how the default class strings task and
taskbody begin with a hyphen (-),
which indicates that this specialization is structural, followed by a space-delimited list
of pairings of topic type and topic element, separated by a slash (/).
This list defines the new element, mapping it back to the more general element—for
instance, mapping taskbody back to the more generic
body.
Listing 1. The task.class is extended from 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>
|
The DITA Open Toolkit (see Resources) is an open source
project that you can use to generate various output types (including PDF) from
a DITA source. Because you can always map new elements back
to more general elements in structural specialization, any new topic types created
using the basic topic types inherit styles from these and from those related
to the original topic schema.
Elaborate on use cases using DITA
As in my previous article, the sample application provided here is introduced exclusively for illustrative purposes. It describes requirements for a simple wizard with a home page, main flow ( also called a "sunny day path"), and an alternate flow. The main interaction between the two actors (the application's user and the system) requires that the user type in his or her name and is subsequently able to modify personal details.
As before, the application consists of a single module containing several pages.
A DITA topic map relating reference
topics describes these pages to the related use cases. The DITA topic map plays
the role of a use case model. Previously I used task
topics; now I will extend the task topic by using
structural specialization to create a new topic type, which I call a
case.
A typical use case consists of a set of pre- and post-conditions that describe
the state of the software described as the use case is triggered and upon its
completion. In addition, you can define state invariants, which are
like rules that do not change over the course of the use case—for
example, "the last name shown on screen will always be capitalized." You can
model these constraints, conditions, and invariants independently using DITA
specialization, probably by extending the concept
topic type. For simplicity's sake, I chose to add these details directly
to the body of the case topic schema.
The basic task topic that is standardly defined as
part of the DITA architecture contains elements for prerequisite, post-requisite,
and context (which bears similarities to the state invariant defined previously).
These elements are all extended from the section heading class in the base
topic, which allows a single heading element to contain multiple paragraphs.
For the use case topic, you want these elements (or similar elements that
extend them) to allow an unordered list of rules because this approach is closer to the
functionality that you are attempting to emulate. To accomplish this task,
extend the DITA unordered list element instead of a section header for
all three categories.
Listing 2 extends the DITA base unordered list
(ul) and list item (li)
elements to create new elements that inherit from them to represent a
collection of preconditions or constraints. Notice that I chose to map
the constraints class not only to the
ul element in the base topic but also to the
prereq element in the intermediary task.
I am replacing the task/prerequisite with case/constraints, so I want
it to inherit style from both predecessors. The constraint
element has no intermediary predecessor. The result of this specialization is that,
while the task topic allowed a single prerequisite,
the case topic requires a list of prerequisite constraints.
Listing 2. Constraint classes in caseMod.xsd
<!-- 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>
|
As you can see from the sample files that accompany this article (see
Download), a similar approach
defines post-conditions and invariants. In each case, an element from the
task topic schema, which was defined stylistically
as a section heading (prereq, postreq,
and context) is replaced by an unordered list
of constraints, conditions, and invariants. Modelling the use case in this way is
more rigorous but allows the case topic to inherit
from the more general task.
The code in Listing 3 shows how the constraint groups are set up in the schema group file.
Listing 3. Constraint groups in caseGrp.xsd
<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>
|
Scenarios, steps, and interactions
At the heart of any use case is the interaction between the software's user and the
software itself (often described as the system). A use case might
involve many actors and interactions, and in a broader sense, these items should
be described using DITA reference topics. References
are typically used to represent real-world objects, so they are a natural fit for
application users, modules, and pages. Again, for the sake of simplicity,
I opt to represent many of these references within the body of the
case topic, although you might reference these
separately from the topic map you use to represent your use case model
and then tie these references into the individual use case topics. Unfortunately,
doing so goes beyond the scope of this article.
At the core of a DITA task is a series of steps, which can be generalized back to
the ordered list class, ol.class. This class is close
to the model you are trying to produce, with the exception of one important
limitation: As defined, a step is not attributed to
an actor. This distinction is important because each step in a use case scenario must be
attributed to an actor. Often, the set of steps that defines a use case represents
a dialogue of sorts between the application user and the system. Other actors
might be involved, but this simple reduction serves for now. The
step element, however, does not. Also, the standard
DITA task topic contains only a provision for a single
set of steps, and you would like your use case to contain not only a main flow but also
potentially several alternate flows.
In Listing 4, observe how the class of the step is extended
to create scenario.class, which is similar to the
predecessor class. The specialized class requires an attribute describing
whether this is a main flow or an alternate flow, defaulting to main.
This multiplicity is handled elsewhere in the schema when the
casebody element is defined. As the
body in a task allowed only a single set of steps to perform a task, the use case
allows multiple alternate steps to perform the use case.
Listing 4. The scenario.class in caseMod.xsd
<!-- 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>
|
In Listing 4, you can also see how the new scenario
element inherits from both steps and
ol. This inheritance allows the new element to
perform as its predecessors when it is encountered by DITA applications such as the
DITA Open Toolkit while still encapsulating new functionality.
Listing 5 shows the class that defines the use case
interaction element, which is again similar to the
step class from which it is specialized, with the
exception that you must attribute this new element to an actor. In this case,
I restricted the set of actors to "system" and "user," but you can add more,
and these actors can reference separate topics (this topic again falls beyond the scope of
this article).
Listing 5. interaction.class in caseMod.xsd
<!-- 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>
|
Again, you can see how this new element is based on a predecessor in
the task topic and a predecessor in the base DITA
topic, inheriting behavior from both.
Now that you have extended one of the DITA basic topics, you can quickly create a
new use case using your favorite XML editor and, based on the new schema, add
content to it. When you have done so, you can create a topic map referencing this
and other DITA topics that you can then use as a use case model and produce a PDF
document from it using the DITA Open Toolkit. You might find that this approach
allows you to leverage one of the collaborative construction environments that are
becoming available for DITA, or you might find that you can leverage the transformative
power of XSL or XQuery to re-purpose your requirements documentation to make it
more useful for different members of your software development team. You can see
a sample case document in Listing 6.
Listing 6. Use case file created using 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>
|
With the DITA framework, you can document how a software application and its users interact. Likewise, software use cases are used to gather information about how a software application interacts with its users, so it stands to reason that the two technologies should be a natural fit. When you use DITA structural specialization to extend the existing topic types into new ones that support your use case-gathering effort, you can maintain compatibility with and leverage existing tooling. After you extend the basic DITA task topic, you can use this new schema to build use cases; from these use cases, you can build a use case model that is flexible and easy to maintain.
| Description | Name | Size | Download method |
|---|---|---|---|
| Sample files for this article | examplecode.zip | 21KB | HTTP |
Information about download methods
Learn
- Create walk-through and acceptance scripts with single-sourced DITA (Piers Michael Hollott, developerWorks, November 2010): Read the earlier article which describes how to leverage single-source documentation using DITA.
- Specializing topic types in DITA (Michael Priestley, developerWorks, September 2005): Explore the mechanics of DITA specialization as described in greater depth.
- DITA topic specialization (Bob DuCharme, developerWorks, February 2008): Read more on many of the features of DITA specialization with DTD.
- An
XML-based information architecture for learning content (John P. Hunt and Robert Bernard, developerWorks, August 2005): Learn about a DITA-based information architecture to develop reusable learning content in this two-part series.
- XSD schema specialization module coding requirements: Learn more about the OASIS design standards for specializing DITA using XSD.
- More DITA-related content (developerWorks, January 2005 - current): Find articles and tutorials about DITA.
- More articles by this author (Piers Michael Hollott,
developerWorks, November 2010-current): Read articles about DITA and other technologies.
- XML area on developerWorks: Get the resources you need to advance your skills in the XML arena.
- IBM XML certification: Find out how you can become an IBM-Certified Developer in XML and related technologies.
- XML technical library: See the developerWorks XML Zone library for a wide range of technical articles and tips, tutorials, standards, and IBM Redbooks. Also, read more XML tips.
- My developerWorks: Personalize your developerWorks experience.
- developerWorks technical events and webcasts: Stay current with technology in these sessions.
- developerWorks on Twitter: Join today to follow developerWorks tweets.
- developerWorks podcasts: Listen to interesting interviews and discussions for software developers.
- developerWorks on-demand demos: Watch demos ranging from product installation and setup for beginners to advanced functionality for experienced developers.
Get products and technologies
- IBM product evaluation versions: Download or explore the online trials in the IBM SOA Sandbox and get your hands on application development tools and middleware products from DB2®, Lotus®, Rational®, Tivoli®, and WebSphere®.
Discuss
- XML zone discussion forums: Participate in any of several XML-related discussions.
- The developerWorks community: Connect with other developerWorks users while exploring the developer-driven blogs, forums, groups, and wikis.
Table of contents
Local resources
Tags
Use the slider bar to see more or fewer tags.
For articles in technology zones (such as Java technology, Linux, Open source, XML), Popular tags shows the top tags for all technology zones. For articles in product zones (such as Info Mgmt, Rational, WebSphere), Popular tags shows the top tags for just that product zone.
For articles in technology zones (such as Java technology, Linux, Open source, XML), My tags shows your tags for all technology zones. For articles in product zones (such as Info Mgmt, Rational, WebSphere), My tags shows your tags for just that product zone.
Popular article tags |
My article tagsSkip to tags list
Popular article tags |
My article tags
