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

All information submitted is secure.

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.

All information submitted is secure.

My developerWorks:

My notifications:

Sign out

Select a language:

DITA topic specialization

Analyze your content and build a specialized DTD

Bob DuCharme (bob@snee.com), Solutions Architect, Innodata Isogen

Bob DuCharme, a solutions architect at Innodata Isogen, was an XML "expert" when XML was a four-letter word. He's written four books and nearly one hundred online and print articles about information technology without using the word "functionality" in any of them. See http://www.snee.com/bob for more and www.snee.com/bobdc.blog for his weblog.

Summary: Many resources are available to explain what Darwin Information Typing Architecture (DITA) topic specialization is and the syntax to implement it, but you still might wonder "I have some content that might be a candidate for topic specialization. What's next?" In this tutorial, walk through a series of steps to evaluate your content's suitability for different DITA topic types, specialize one of those types, and test your specialization using the DITA Open Toolkit.

Date: 26 Feb 2008
Level: Intermediate
PDF: A4 and Letter (58 KB | 16 pages)Get Adobe® Reader®

Activity: 13540 views
Comments:

Analyze your content for its fit with DITA

DITA provides the greatest benefit for content whose structure matches up well with one or more of the structures offered by the DITA standard. What do I mean when I say "matches up well"? These steps show how to review your content to find out.

Step 1: Think about which topic type best suits your content

If you're even considering the use of the DITA architecture, you can probably treat your content as a series of discrete topics to mix and match into larger works for output into different media. A classic example is recipes. Everyone needs to eat, and the mix of structure and flexibility that you need for a recipe document model is similar to many of the content classes that people use DITA for: maintenance manuals, instructional guides, and other technical and reference materials.

The first question to address is which of the main DITA topic types are most appropriate to your content: task, reference, or concept. The DITA specification (see Resources) provides some background on the typical use of each of these topic types. Because the task and reference topic types have structures that are more specialized than that of the more flexible concept topic type, you'll want to consider how well those structures might apply to your content. Look at the structures of these three topic types, and look at your content: what are the potential parts, and what roles do they play? How well do the parts of your content match up with the parts of each topic type?

As you make this decision and others described in this tutorial, don't worry about making a choice that causes problems further along in the specialization process. It's an iterative process. Any subset of the steps can be a loop whose repetition gives you greater focus on the best design.

The preparation of a particular food dish is pretty clearly a task, as opposed to a concept or a reference topic (both of which can easily serve roles in the front or back of a cookbook). Still, you want to make sure that the DITA task structure fits the recipes well.

Step 2: Mock up a content sample using the DITA DTD

Open an XML editor that can use the DITA DTD and try to create a valid DITA document with a unit of your content that you would consider a topic. For example, I stored a recipe in the DITA task shown in Listing 1.

Listing 1. First sample content document

                    
<!DOCTYPE task PUBLIC "-//IBM//DTD DITA Task//EN" "task.dtd">
<task id="r1">
  <title>Blueberry Pie</title>
  <shortdesc>Everyone will be <i>so</i> impressed when you pull it out of the
  oven!</shortdesc>
  <taskbody>
    <prereq>
      <ul>
        <li><p>1 can blueberry pie filling</p></li>
        <li><p>2 pie crusts, available at supermarket</p></li>
      </ul>
    </prereq>
    <steps>
      <step>
        <cmd>Pour the contents of the can over one of the pie
        crusts.</cmd>
      </step>
      <step>
        <cmd>Put the other crust on top of that. Press down around
        the edges of the top crust with a fork to mush it onto the outer
        edge of the bottom crust. Poke a few holes in the top crust with
        the fork to let steam escape while cooking.</cmd>
      </step>
      <step>
        <cmd>Cook according to the directions that came with the
        pie crusts.</cmd>
      </step>
    </steps>
  </taskbody>
</task>

Although DITA specialization lets you create new names for the elements that contain your content, you're better off if the DITA elements describe the sections they contain reasonably well. How well do the names of the task topic's elements describe the parts of a recipe? The DITA title and steps elements are clearly a good fit for the corresponding parts of a recipe. The prereq element isn't a perfect fit for a recipe's list of ingredients, but still, you should have all the right ingredients before you begin to assemble a dish, so ingredients qualify as prerequisites.

Step 3: Mock up more content samples using the DITA DTD

In other words, don't skimp on Step 2. To do the best job on the later steps of this process, you should spend most of your time on this step.

Don't just use typical examples of your content. Seek out the more unusual cases, because it's better to address their odder features now than to try to account for them in a system that's already been deployed to multiple desktops. The following recipe example only has one new item that the first one didn't have: the little note at the end of the recipe after the steps element. Given the choice of example, postreq, and result elements that can go after a DITA task topic's steps element, I decided to use result for the little note.

Listing 2. Second sample content document

                    
<!DOCTYPE task PUBLIC "-//IBM//DTD DITA Task//EN" "task.dtd">
<task id="r2">
  <title>Corned beef and cabbage</title>
  <shortdesc>A simple meal to make on St. Patrick's Day.</shortdesc>
  <taskbody>
    <prereq>
      <ul>
        <li><p>1 corned beef</p></li>
        <li><p>4 peeled cloves of garlic</p></li>
        <li><p>1 head of cabbage cut into 3" chunks</p></li>
      </ul>
    </prereq>
    <steps>
      <step>
        <cmd>Rinse corned beef.</cmd>
      </step>
      <step>
        <cmd>Bring enough water to cover the corned beef (with a few inches left
        over) to a boil.</cmd>
      </step>
      <step>
        <cmd>Add the corned beef and garlic to the boiling water and cook
        for 30 minutes per pound of corned beef.</cmd>
      </step>
      <step>
        <cmd>Add the cabbage to the mixture fifteen minutes before the
        corned beef is done.</cmd>
      </step>
      <step>
        <cmd>Drain and serve with hot mustard.</cmd>
      </step>
    </steps>
    <result>Your mother would have put in the cabbage a lot sooner, but that
    turns it into a pasty mush, which is what makes a lot of people hate
    cabbage.</result>
  </taskbody>
</task>

You don't have to mock up dozens of your articles in DITA, but you should scan through a few dozen, looking for document components that your examples have not yet accounted for. Then, create examples that account for them.

The examples here only have one inline element, the i element enclosing the word "so" in Listing 1. As with block elements, this is the time to determine which of the standard DITA inline elements provide the best fit for what you need and to evaluate how good that fit is.

Once you've an idea of how well your content fits into the standard DITA model, you're ready to think about how to customize it for an even better fit.

Comments