An XML-based information architecture for learning content, Part 2: A DITA content pilot

Using DITA XML to develop reusable learning content

Find out how topic-based DITA XML can provide the basis for developing an information architecture for single-sourced XML learning content. Part 1 of this two-part series presented a set of extensions to DITA XML that provide the starting point for a unifying content model for learning. Here in Part 2, the authors test their assumptions against pilot content from a training course developed to support a component feature of IBM® DB2 Query Monitor™, and then report their findings and suggest important next steps.


Robert Bernard (, DB2 Training Developer, IBM

Photo of Robert BernardBob Bernard is a certified training specialist and training course developer for IBM DB2 software. He is chief evangelist for encouraging IBM learning developers to make the move to structured authoring with DITA.

John P. Hunt (, DITA Learning Architect, IBM

Photo of John HuntJohn Hunt charts the overall technical direction and strategy for product user assistance for IBM portal and collaboration software. He has designed award-winning help systems and spearheaded his team's migration to DITA XML and a topic-based information architecture. For DITA, he has driven the move to support learning content.

11 August 2005

The first article in this series defined a set of DITA topic types and other extensions that provide a framework for developing an XML content model for authoring and delivering learning content. We identified key phases in the DITA end-to-end process model for developing and delivering learning content, including:

  1. Identify and model learning objectives and goals
  2. Organize objectives into lessons and modules
  3. Identify existing topics and develop new topic-based content that supports the objectives
  4. Develop topic content for labs, exercises, and assessments, as appropriate
  5. Write overviews and summaries for each objective and the overall course
  6. Structure the topics for delivery in a particular course with a map
  7. Use XSLT to process the map and topics for the particular deliverable

In this article, we describe how we applied this DITA process model for learning to a case study course using content from an existing course on the IBM DB2 Query Monitor. This course was originally developed for delivery as instructor-led training (ILT), with content provided in the form of instructor slides, an instructor guide (printed PDF), and a student guide (printed PDF).

About the pilot course content

The pilot course used for this case study -- although short (duration is 4 hours) -- is a complete course, including labs and exercises, stated learning objectives, lesson summaries, and other structures common to a classroom-based instructor-led training course.

The existing printed student guide for the Query Monitor course contains the following content:

  • Front matter
  • Course Introduction
  • Module 1 -- Using Query Monitor
  • Module 2 -- Using Filters and Profiles
  • Course Summary
  • Appendix A -- Installing Query Monitor


The included file (see Download) provides a proof-of-concept implementation of a set of proposed DITA topic specializations to support authoring and delivering learning content. It also provides a set of sample topics and map from pilot course content about the IBM DB2 Query Monitor.

A key goal for the pilot was to explore how content originally conceived as a single large course could be split up and chunked into topic-based content segments, and reorganized as reusable learning objects (RLOs) for delivery as self-contained course modules. This would enable us to position this content for later delivery as an e-learning course.

Reworking the course as DITA

In reworking the Query Monitor course, we applied the DITA process model adapted for learning, as follows.

1 and 2. Identify the learning objectives and organize them into modules

First, we identified two module-level learning objectives for the Query Monitor course:

  • Using Query Monitor
  • Using filters and properties

3. Develop topic-based supporting content

Next, we identified the tasks, concepts, and reference information needed to support the lesson-level learning objectives within each of these module-level objectives.

  • Using Query Monitor
    1. Navigate through the Query Monitor ISPF interface
    2. Use ISPF commands
  • Using filters and properties
    1. Use filters to refine the level of query detail displayed
    2. Define tasks to monitor by creating monitoring, application, and exception profiles
    3. Analyze and explain the results of a monitored query session

4. Develop labs, exercises, and assessments

The source materials for the original course did not include lab exercises or assessments. We reserved a place for those topics in our overall design, and plan to test them when we develop e-learning deliverables in the next stage of our pilot.

5. Write overviews and summaries

We created topics for overview and summary content for each of the two module-level objectives, and an additional set of overview and summary topics for the course as a whole. More extensive courses would include overview and summary topics at each level of the course structure hierarchy -- for example, at the lesson, module, and unit levels, as well as the overall course level.

Learning overview
Listing 1 is a sample learning overview topic from the pilot course. This topic provides mainpoints content, a learning objective, duration, and other overview information.

Listing 1. A learning overview topic
<?xml version='1.0' encoding='utf-8'?>
   <p>At the end of this module, you will be able to:</p><ul>
    <li>Navigate through the Query Monitor ISPF interface</li>
    <li>Use the various ISPF commands</li></ul>
  <duration><title>Duration</title><p>2 hours</p></duration>
    <li>Navigate through the Query Monitor ISPF interface</li>
    <li>Use the various ISPF commands</li></ul>
  <prerequisites><title>Course prerequisites</title>
   <ul><li>Basic SQL and DB2 skills</li></ul>

Learning summary
Listing 2 is a sample learning summary topic. In this case, the entire summary is provided in the mainpoints content.

Listing 2. A learning summary topic
<?xml version='1.0' encoding='utf-8'?>
<learningsummary id="DB2QM238_SUM">
   <p>You should now be able to:</p>
    <li>Navigate through the Query Monitor ISPF interface</li>
    <li>Use the various ISPF commands</li>

6. Structure topics for delivery with a DITA map

To create a map of topics for a learning module, we selected the topics we wanted in the unit, and then placed topics in the order we wanted them to flow. We used a topichead element to group the topics for each learning module.

Listing 3 is a portion of the DITA map for "Module 2 -- Using Query Monitor" of the pilot course.

Listing 3. A learning map
<map title="DB2 Query Monitor Course">
 <topichead navtitle="Module 2: Using the Query Monitor">
   <topicref href="querymonitor_over.xml"/>
     <topicref href="ispf_nav_ref.xml"/>
     <topicref href="main_panel_ref.xml"/>
     <topicref href="qm_discovery_task.xml"/>
     . . .
     <topicref href="planview_concept.xml"/>
     <topicref href="dbrmview_concept.xml"/>
     <topicref href="activate_task.xml"/>
     <topicref href="deactivate_task.xml"/>
   <topicref href="DB2QM238_Summary.xml"/>
   <topicref href="DB2QMLAB201_practice.xml"/>

Here's the list of topics from the map, showing the nested topic type and title:

  • Overview: Using Query Monitor
    • Reference: ISPF Navigation
    • Reference: Main Panel
    • Task: DB2 QM Subsystem Discovery
    • . . .
    • Concept: View Operational Summaries: Plan
    • Concept: View Operational Summaries: DBRM/Package
    • Task: Activating a Monitoring Agent
    • Task: Deactivating a Monitoring Agent
  • Summary: Summary
  • Practice: Exercise 1 -- Navigating the Query Monitor Interface

7. Process the map to produce the deliverable

We used XSLT, Ant, and FO processing available with the DITA Open Toolkit (see Resources) to process the map and topics into the PDF deliverable that's used for the ILT course. Figure 1 shows an example of the output from this processing.

Figure 1. Example PDF output of Main Panel topic
Example PDF output of Main Panel topic

The challenges

In the initial project design stage and during the pilot implementation stage, we faced several challenges related to making the move to topic-based, information-typed content development.

Thinking in topics

First, from past experience in developing the original course, we focused on telling a story with a narrative approach to content development where one piece of information flows easily into the next. In this approach, course developers give little regard to the categorization of the content into content types. For example, conceptual information often freely mixes with the reference and task information needed to support the concept.

A major challenge we faced in reworking the pilot content as topic-based DITA involved the mindset change to thinking of the content as discrete chunks of information, rather than as one single, long-flowing narrative.

Structuring content with information types

Second, in addition to learning how to break down our content into topic-based units, we also needed to apply discipline in how we assigned specific topic types to that content. This required us to take what was formerly a mixed paragraph, or maybe a whole page of information, and chunk it down into discrete topics that contained individual types of information, with respect to concept, task, or reference types.

We discovered the key rule we needed to abide by: Each chunk of information has to be a complete thought about a single type of content. It has to convey the knowledge of that one specific piece of information without directly overlapping with information in other topic-based chunks.

Minding the context

Finally, we faced the predicament that, after chunking the information down into individual types, the role of the content within the overall learning context can get lost. In this case, it might at first appear difficult to break up the information into topics and types by these rules; it's tempting to resort to the usual narrative approach and simply leave the content intact as a way of ensuring the original completeness of thought.

The challenge here is to learn how not only to assign content to one of the agreed-upon topic types (concept, task, or reference), but also to mind the context of the overall learning objective. It's crucial to know where each topic resides within the learning objective, as provided by the essential context defined in the DITA map. The individual DITA topics have no inherent context in themselves, but acquire context according to their role within the map.

In a nutshell, authoring and delivering content using topics and information types is a skill that takes time and experience to learn how to apply to content.

Summary and next steps: e-learning, SCORM, and beyond

This pilot project provides an initial reference point for using DITA XML to support best practices in developing and delivering learning content. We've only just begun: We need to do much deeper work against richer and more diverse learning content to further validate, refine, and extend the design and process framework outlined here.

Specifically, we plan to extend our explorations along the following lines:

  1. Bring more focus on specific reuse and repurposing of educational content, both within teams and across teams, as well as across functional boundaries.
  2. Convert more robust courses into DITA.
  3. Develop targeted output transforms that are specific to learning deliverables needed for instructor-led training:
    • Student guide
    • Instructor guide
    • Overhead slides
  4. Extend DITA map specializations to include course-level and unit-level mapping.
  5. Develop map processing to support delivery to a SCORM-compliant manifest and content package.
  6. Continue refining the learning topic types, in response to specific content requirements that arise in actual course content. Focus in particular on developing a deeper understanding of the content design, deliverables, and processing requirements for the assessment and practice topic types needed for e-learning and SCORM.

We invite your involvement in these initiatives, and encourage you to participate by joining in the discussions and helping to extend the DITA standard through the activities of the DITA OASIS Technical Committee.


The authors would like to thank IBM colleagues Eric Sirois and Don Day for their help in preparing the schemas and sample topics in the download.


Sample DITA topics for this articlex-dita9b-learning.zip660 KB



Get products and technologies


developerWorks: Sign in

Required fields are indicated with an asterisk (*).

Need an IBM ID?
Forgot your IBM ID?

Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name

The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.


All information submitted is secure.

Dig deeper into XML on developerWorks

Zone=XML, Information Management
ArticleTitle=An XML-based information architecture for learning content, Part 2: A DITA content pilot