Content reuse is one of the main reasons why organizations move away from unstructured writing and introduce the Darwin Information Typing Architecture (DITA) standard. It’s a promise of freeing authors from the mundane and error-prone task of copy-pasting or from mastering the find & replace mechanism. For many, reusing content in a structured and controlled way is a dream come true.
Whether you’re considering DITA or you have already adopted it, we hope this summary is a helpful overview of the most common DITA reuse mechanisms:
- Reusing topics and groups of topics
- Reusing parts of a topic
- Reusing variable phrases
- Filtering your content
The most basic form of reuse is using one topic in multiple deliverables. This is possible:
- When the content of a topic is identical for different audiences, products, deliverable types, and so on. In this case, you simply add the same topic in multiple maps. A good example of this type of reuse is a topic with copyright information that is identical for all deliverables your organization publishes.
- When topic content is identical, with the exception of the product name, product-specific information, or even user interface elements. In this case, you can still reuse the topic and add variables, which we’ll discuss later in this post.
To add a topic to a deliverable, you attach it to a map. To reuse a topic in multiple deliverables, you simply attach it to multiple maps. Maps are how DITA bundles a set of topics together to work with them as a group.
Here is an example of reusing one topic in two maps. The group of Topics (blue) represents your Content Library and you can see that the Introduction, Maintenance, and Troubleshoot topics are reused in both maps.
Apart from topics, you can also reuse entire maps. It’s a powerful method of reuse, for example, if you need to maintain a catalog of all product documentation and also be able to print a product deliverable independently.
How it’s done: You can reuse topics and maps directly by including a reference to a specific topic or map using a topic reference (
You can also reuse parts of topics, for example, steps or notes, by using content references (
Here is an example of how you reuse steps from a warehouse topic by using
How it’s done: You can reuse content by creating
Reusing variable phrases
Another way of reusing content is with content key references (conkeyrefs). Conkeyrefs are frequently used for variable phrases (variables), or small bits of content that might change. When you use variables, you’re not actually inserting the content that’s displayed, but creating an indirect reference to the content, which, again, is like saying ‘I’m going home’ rather than ‘I’m going to a specific address.’
You can use variables for information such as product names, company names, product-specific information, and even user interface elements.
A good example of using
Here is an example of two maps that reuse a Toasting Bread topic. Each map is dedicated to a different product: Classic Toaster or Lightning Toaster. Reuse of the Toasting Bread topic is possible thanks to variables added via
Each map contains a different Variables Warehouse topic with the same key attribute defined as vars. Each of the Variables Warehouse topics contains a product variable with the same ID (
The Toasting Bread topic has a
How it’s done: With
Filtering, or conditional processing, is another mechanism for reusing content by adding attributes (let’s call them ‘tags’) to content that varies for different audiences or publications so you can filter it out when publishing. With conditional processing, you can provide targeted and personalized content to a range of users. Content for multiple conditions can exist in one topic, so you don’t have to maintain multiple versions of a file. You simply need to apply ‘tags’ to elements to identify specific audiences or platforms the content is meant for. During publish, a DITAVal file, that contains processing conditions, controls which content is included in the output and which is excluded.
So, if you have a map that contains topics with elements that are meant only for an internal audience–for example, notes with internal-only information–you can ‘tag’ them as internal and, during the publishing process, define conditions that will exclude internal content from all customer-facing deliverables, such as a User Guide. With conditional processing, you can also control which topics are included in a publish by ‘tagging’ elements that link to topics (
Here is an example of a topic with conditional processing applied. The Classic Toaster Introduction topic contains some content meant for users and a note meant for internal testers. During publish, the DITAVal for customer-facing outputs will exclude from the output all content that is ‘tagged’ as internal. As a result, the published User Guide doesn’t contain the internal note in the Classic Toaster Introduction topic.
How it’s done: You ‘tag’ your content by defining conditional processing attributes, including Audience, Platform, Product, and Other Props. Then, in a DITAVal file, you create conditions to include or exclude ‘tagged’ content. You apply the DITAVal file to your publishing job to produce conditionalized output.
Organization of reusable content
If organized incorrectly, reuse can give you a headache. I mean, a nasty headache. To sleep well and avoid headaches, always reuse your content from a warehouse topic or “single source of truth”. This is especially important when you reuse content below the topic level, for example, a paragraph.
The rule of thumb is: avoid spaghetti code! Spaghetti code is created when you reuse content from a topic that is not a warehouse topic. As a result, it’s easy to forget which topic is the source of reuse. When you don’t know that, you’re likely to accidentally delete or modify an element that is reused in other places, making your content incomplete. To avoid it, always keep your reusable content in a dedicated file and reuse from there. As a result, there’s no spaghetti code, your content is safe and easy to maintain, and you don’t need to worry about nasty headaches.
Reuse and Localization
Since we’re talking reuse, it’s a must to mention localization because your approach to reusing content may impact the translatability of your content. In other words, if not organized well, reuse can significantly increase your localization costs or even make parts of your content untranslatable. There are a few very important rules you need to remember when reusing content that needs to be localized:
- Whenever possible reuse block elements, for example, paragraphs or steps. Don’t reuse parts of content inside an element, for example, part of a sentence.
- If you need to reuse content inline, reuse whole sentences only.
- If you need to reuse parts of sentences, for example, as variables, make sure that they won’t need to be localized or that they won’t trigger localization issues. Variables are localized separate from the rest of your content, so any terms that need the context of the sentence to localize could result in issues. For example, inflection and word gender in other languages can affect localization if you reuse a noun. On the other hand, proper nouns, which often should not be translated, are a good candidate for variables.
Typically, reuse strategies include a combination of some or all of the above mechanisms. There’s no one golden reuse strategy to follow. It really depends on the nature of your content, product requirements, audience needs, output types, tool limitations, team know-how, and more. Make sure that your reuse strategy is clear, follows the localization and reuse organization guidelines, and is applied consistently by everyone on your team. This will require some consideration and time prior to implementing your reuse strategy. But it’s worth it. Remember, you want to avoid nasty headaches, right?
These are not all of the reuse mechanisms DITA offers. We’ve discussed only the most common ones. easyDITA supports all DITA reuse mechanisms. Let us know if you’d like us to write a post on exemplary reuse strategies or any other aspects of reuse. We’ll gladly do that!
Latest posts by Gosia Radymiak (see all)
- Webinar: How to Reuse Structured Content With DITA - February 15, 2018
- How to Reuse Structured Content With DITA - October 24, 2017