3 Useful Things DITA XML Can Do for Your Content
December 29, 2020
It’s pretty common for technical writing and information development teams to understand how effective DITA is, but the value of DITA has to translate outside of content development. Aligning the capabilities of DITA with overarching business goals is a surefire way to turn some heads. And the heads that need turning want to know what DITA can do and why they should care.
Articulating this requires stepping outside the technical writing mindset and into displaying DITA as a viable business asset. This article will look at the real usefulness of DITA XML and will present capabilities that show just how effective DITA XML can be for your organization’s content.
Content & Product Cannot Be Apart
First, a note about content. Start by acknowledging that complex products that require user manuals and other documentation are inextricably linked to content.
Organizations build products with the goal of creating something useful and content describes how to use those products effectively. Very few people, regardless of their interest in a product, are going to put in the work it takes to fully learn it.
That’s why there must be content that will answer questions, address concerns, and explains new features. As a product and the related content evolves, it’s paramount to be able to produce and deliver that content at scale. Which is a lot of work!
DITA is great at taking some of that content maintenance workload away. Let’s see how.
Reuse
Any helpful content library is sure to grow. Without structure, massive content libraries easily grow unwieldy. Content creators know this, but it’s largely hidden from departments outside of the department responsible for creating and maintaining that content.
DITA content is created in topics. More specifically, a DITA topic is a piece of content that answers a single question or addresses a single idea such that it can exist on its own. They can be moved, used, and reused in multiple places to assemble complete content deliverables. Like this:
This is awesome because it eliminates time and resources wasted on copy-pasting or rewriting reusable content. DITA content works in maps that connect several topics together to create a final piece of content.
In the figure above, the Maintenance Manual and Engineer Manual share three of the same topics and those three topics can be reused in the two different deliverables accordingly.
Then, whenever a change needs to be made in one of those topics, it only needs to be made in one place and the changes will be seen wherever that topic is used. That beats having to make manual changes in each deliverable a topic is used; imagine having to make those changes in 100 different places (or thousands).
Time saved is money saved (a helpful thing to reiterate). Reuse also helps rein in the propensity for human error associated with manual content changes. Instead, edit in one place and see the connected changes wherever they’re located in your content.
Audience Filtering
Conditional processing in DITA XML allows your content to be filtered for different audiences. Content creators and stakeholders both understand that different audiences benefit from different content.
For example, a new user isn’t going to want to sift through a manual meant for engineers. DITA uses conditional processing to filter content so that users can access content specifically tailored to their needs, skills, and goals.
It looks like this:
<concept id="concept-9038" xml:lang="en-us">
<title>This is a Content Filtering Example </title>
<shortdesc>This will show how a basic example of how content can be filtered for different audiences. Observe.</shortdesc>
<prolog>
<author translate="no" type="creator">Tim Ludwig <tim.ludwig@jorsek.com></author>
</prolog>
<conbody>
<section audience="external">
<title>This is a section that your customers need to see</title>
<p>In this section, there is information that your customers, users, prospects -- basically anyone who wants to use your product -- needs to see. </p>
<p>No, seriously, they need this. If we've done this right, the document will end here and there will be no further content below this.</p>
</section>
<section audience="internal">
<title>This is a section that your internal personnel need to see</title>
<p>In this section, there's a bunch of information that's only important for people in your organization. Users don't need to see this stuff. In fact, this stuff is likely to confuse them.</p>
<p>When we publish this whole piece of content, let's make sure the users can't see this section. </p>
</section>
</conbody>
</concept>
I’ve created a simple DITA concept topic that shows a basic example of conditional processing. Notice the topic contains two <section> elements with <audience> attributes having the values "external" and "internal". One’s meant for external audiences and one’s meant for internal audiences.
The two values allow the content to be deployed as separate deliverables that correspond with the given audiences without having to recreate the content in different topics. Author in one topic and filter it based on the intended audience (this is called conditional processing in the DITA world). While this example is a simple one, imagine how helpful this would be when you need similar content going to several different audiences.
Multichannel Publishing
When we philosophize about content, it’s easy to think of it as the physical deliverable, like a webpage, PDF, or printed manual. What DITA helps us understand is that content is the idea that fills those deliverables and that it’s not attached to any single output.
This is where multichannel publishing comes into play. DITA XML is structured content created completely separate from formatting. This way, regardless of the number of physical deliverables you need your content to fill, DITA content will publish to each of them. Write once, publish everywhere.
This is a huge time saver because formatting for several different deliverables can be more time-consuming than creating the content itself. Thus, with DITA, you can purely create content without worrying about formatting it to a certain output and publish it directly to whatever deliverables you need.