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.
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.
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
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.
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
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.