One of the main drivers in Open DITA is allowing writers with little or no XML skills to benefit from the most important reuse capabilities of the DITA standard. So let’s cherry pick from the rules of the Open DITA manifest and explain how they achieve reuse of your content.

But before we get to that, let’s take a step back and consider WHY we want to reuse. Let’s be honest. Reusing content creates a certain amount of complexity. For that reason we had better make sure that this complexity is worth our while.

Oh, and by the way - very often that level of complexity is already there, it’s just not always technical. Very often writers know that if they update a section describing a feature in one product, they must also update the documentation for variations of that product. If a legal note is rephrased, they need to find all the places it is used and copy/paste. The complexity is already there, and at the end of the day, the technical dependencies can actually help you manage these dependencies and ensure that none are missed.

This leads us to one of the main benefits of reuse: consistency. Let’s keep it simple and stick with the most important benefits:

• Consistency across your documentation - When you reuse a topic, a piece of text, or an illustration, this minimizes ambiguous interpretations of the content. Honestly, if people are looking to enjoy variety in language, they will pick up a novel rather than my documentation.

• Less content to maintain and update - The second benefit is also the most popular among business cases for structured writing projects. If I am reusing a topic or a legal note in five different places, I have updated all five by just opening up one topic and making the change.

• Translation costs cut dramatically - When there is less content to source all of your deliverables, there is less content to translate. Often, this alone can drive the business case of a structured writing project because of the cost involved in translating 10 or 20 languages.

We should be honest with ourselves - reusing a topic does not mean that I just saved 80% of the time it would have taken to update all five topics manually. First of all, it does not take as long to copy/paste as it does to author content. Second, in most cases I need to make sure I know where this content is used before I edit it.

On the other hand, a proper CCMS will help me find out. In Dx4, this feature is called “Where used.” Without content reuse, I need to know and find the places to update, and I might even need separate bookkeeping to keep track. Regardless of whether this complexity is stored separately or in my own personal memory, it is prone to human error, and the risk of me missing something cannot be disregarded… and then we are back to the reuse benefit of consistency.

The maintenance effort saved by reusing content depends on how well you architect your content. If it’s a mess, the time you save on authoring can very well be spent on managing content and checking dependencies. This is part of the reason why Open DITA does not require all of the mechanisms for reuse that you can use with DITA XML 1.3. We have intentionally limited Open DITA to the most commonly used reuse strategies, and the ones that require less expertise and create less complexity. If you want to go all in, you should go with full-fledged DITA XML – no doubt!

Looking at the Open DITA manifest there are number of rules that enable you to reuse content in different ways. These are: 

1. DITA map support
2. Content references (conref)
5. DITAVAL support
9. Support automated processing
10. Support styling, layout and formatting through a standard styling language

Reuse content for differently styled publications

Let’s start with #10. Because an Open DITA implementation must support a standard styling language, you can create publications with different stylesheets from the same source content. This means that you can use the same content for publications with your commercial branding and also unbranded publications, e.g. for OEM purposes.

Reuse content publishing to different output formats

#9 requires an Open DITA solution to allow automated processing. This can potentially allow you to do all kinds of things with your content, but let’s keep it simple. Automated processing allows you to transform your source content to a variety output formats. Content consumers today are used to being able to access content on different platforms and they want the content to adapt to that platform. With automated processing, I can publish the same content to PDF and Word files, to web portals that adapt to all screen sizes, to e-books, apps, and chatbots… and to whatever comes next.

Reuse topics across multiple maps

#1 ensures that an Open DITA solution provides the most fundamental principle of the DITA architecture: reusing topics across multiple maps. Supporting DITA maps means that content is stored separately (in topics) and the structure of a publication is stored separately (in the map). The map defines the table of contents of the deliverable, and it defines the individual chapters and sections of the deliverable, but the content is stored separately. This allows us to use, for example, a topic with a feature description in several publications describing different variations of a product. And we may even be able to give the marketing guys a hand, and let them use it in the marketing collateral.

An added benefit of requiring DITA maps for an Open DITA solution is that we can mix and match different topic architectures – even full-fledged DITA XML topics – sourcing disparate content to the same deliverable.

Reuse snippets of text across topics

#2 is perfect for notes and other little snippets of text that you want to make sure are exactly the same all over – no matter how many times they appear in your content. A content reference (or conref) is basically a placeholder in your topic that has a pointer to a piece of text in another topic. My favorite example is the legal note that has been carefully phrased by the legal department. This note can be sourced from a topic that only the legal department can edit. Content references throughout the body of documentation ensure that you can use the note wherever you want, but that you cannot change it. If the legal department needs to rephrase the note, this can be done in one place and automatically updates all placeholders throughout your content.

Filter out pieces of content

#5 requires an Open DITA solution to support DITAVALs. DITAVALs are files that define a filter for your content. They allow you to include content in topics that cover several variants of the topic. At publication time, you select a DITAVAL filter that ensures that you get the content in your publication that applies to the variation you are looking for. Your product may have different names depending on the market you are selling to. For example, you can create a single topic that actually contains all of these different product names. When you publish using the appropriate DITAVAL filter, the publication contains only the relevant product name.

A major advantage of Open DITA is allowing writers with little or no XML skills to benefit from one of the most important capabilities of the DITA standard: reuse. By applying 5 rules from the Open DITA manifest, you can: reuse content for publications with different styling, reuse content publishing to different output formats, reuse topics across multiple maps, reuse snippets of text across topics, and filter out pieces of unneeded content. When you recycle pieces of content, you guarantee consistency across your documentation, ensure there is less to maintain and update, and cut translation costs. These clear benefits outweigh any added complexity to your content production.