Structured Writing Part 5: Applying DITA Elements

Let’s say you’ve done a content audit to determine where you should reuse content, you’ve selected your tools and now you’re ready to develop content in XML using DITA. I’ll put the pieces of the last few blog posts together and share what it looks like when you apply DITA elements to content. I’ll also cover how to account for topic variations and why you should develop an information model.

Example of Applying DITA Elements

Let’s look at an example. Based on the concept of content reuse and organizing content around the smallest chunk that makes sense, let’s say we have a topic called “How to Verify Package Contents” that has a few simple parts to it. This topic should be identical in three different products so we decide to make it its own topic and reuse it across all three products. The topic contains instructions so we want to make it a task information type. Within the <task> element, there are more than 20 additional elements that you can use to structure the task content. We decided to use a <context> element for the introductory paragraph, <steps> for the procedure and <result> for the conclusion of the procedure. Here’s how the structure type, content and associated DITA element might look like for our example:

Accounting for Topic Variation Using Conditional Attributes

Using our example above, let’s say we have a fourth product (Product D) whose instructions are the same except there’s one additional step. You can still reuse the topic by setting up conditional attributes, one of which is product, in your XML authoring program. Here you can add your different products. Then when you have some variation in content, you can apply the product conditional attribute to the specific element(s). When you publish the content for the product, the reused topic will appear along with the specific product content.

So DITA gives you the flexibility to handle exceptions, which really helps to build a content reuse case and it again reduces authoring and translation costs.

Validating the Structure

A DTD (Document Type Definition) is a set of markup declarations that validates the structure. As you create content in XML, the DTD will check for structural rules and it will give you an error if you try to do something that isn’t part of the rules. XML authoring programs come with a DTD.

Documenting Elements in an Information Model

There are many DITA elements and there’s usually more than one way to define the structure, so you should work with your team to establish how to structure your content. For example, after you work through this process, you may find that you only use 20-30 elements out of all of them. The decisions you make in how to structure your content should be captured in a document or web output called an information model so that writers create content consistently. An information model should contain which elements to use, a description, the context and examples.

Conclusion

The process of applying DITA to content involves making content reuse decisions and then using the DITA elements to write the content. In the final blog post in this series, I’ll talk about publishing XML content.