Select Page

High-quality content serves different audiences effectively. Audience filtering makes sure you’re not leaving anyone out without the hassle of duplicating your content. 

 

 

When you want to tailor your content to the needs of particular audiences and to reduce duplication, conditional processing with DITA makes this a reality. It’s a capability that has vast potential across all of your content. We’ll show you how. 

 

 

What is This Content Filtering Feature?

Content filtering and conditionalizing are terms we use interchangeably. 

One of the many conveniences of developing content with DITA is conditionalization. I mentioned the interchangeable terms because you have the ability to put conditions on your content so that you can filter it specifically for your separate audiences. This way, these audiences only see the parts of your content that are appropriate for their needs or meets their access level.

For instance, your customers don’t need to see engineering-heavy content in a user guide. Conditionalizing allows you to write one document that contains both user-oriented content and engineer-oriented content. The publishing process applies filtering to that content, and the net result is two documents that meet both audiences’ needs (without forcing them to wade through irrelevant content). 

 

Why Does Content Filtering Matter?

Few organizations publish universally accessible content. 

When you have content that shares many similarities, but with enough differences to justify several versions, conditionalizing is faster than writing those several different versions. Additionally, users don’t have time to waste trying to figure out what content is most applicable to whatever it is they are trying to accomplish or learn. Content filtering provides a way to streamline and focus content for specific users, products, and more. 

There’s some planning with this. You need to identify your audiences and select the parts within the content that they need or don’t need. 

Think about security clearances, for instance. I’m sure their documentation is carefully maintained, but the example is salient. Say you’re a governing body with three security clearances: Top Secret, Middle Secret, Not Secret. 

Your content developers are Top Secret clearance. Still, they must redact content for each of the lower levels. Content filtering and conditional processing in DITA allow this. But, let’s see how it works in action.

 

How To Publish Filtered Content With easyDITA

Let’s get some examples published. For the sake of simplicity in this example, we’re going to publish content meant for two different audiences. 

  1. Personnel in your organization, your internal audience. 
  2. People outside of your organization, your external audience.

The content will be largely the same, but there are some notes that company employees need that people outside of your company do not. We’ll conditionalize the content to display only what’s needed for each audience.

Look at the content we have in this ditamap. 

If I published this as it is here, the end result would be a formatted version of this exact content. Every viewer would see the same version. As the content states, there is a section that only internal personnel needs to see. To enable that, we conditionalize the document to serve the two audiences.

To conditionalize it, there are a few steps we need to take. 

  1. Identify which content to conditionalize. Nothing will happen if we don’t select the content we want to filter, so let’s do that first. I want to publish this document for my external customers, so I’ll filter out content that is meant for internal personnel. I’ll highlight the content I want to conditionalize.
  2. Once the content is selected, I’ll click the Attributes tab along the sidebar. Several fields will show, but we’re concerned with the audience attribute. In that field, I’ll type the value internal and press enter/return on the keyboard.

 

Now, if you’re wondering how I knew to type internal, you wouldn’t be alone. In easyDITA, there are DITAVals that we’ve built for conditionalizing content. For more on how DITAVals work, check out the OASIS DITAVal Documentation

In this particular DITAVal (customer_facing.ditaval), we specify exactly what we did in the previous animation. 

 

  • Attribute: audience
  • Value: internal
  • Action: exclude

Put plainly, when this DITAVal is applied, it makes sure that any content with the attribute audience and the value internal is not published. Once we do this, you’ll notice a little sidebar note in the document with the value internal, specifying which content has a condition applied. 

Now it’s time to publish our customer-facing content. 

In the top-right corner, click the Publish button. On the next menu, you’ll see all sorts of different publishing options. For this example, we’re just going to choose our Jorsek Branded PDF template to display conditionalized content. 

When you choose the Jorsek Branded PDF, you’ll see the next menu that shows a few options. Among those few options, we’re concerned with args.filter and the blue button next to it. Click the blue +Add file button, then recall that same DITAVal we used earlier — customer_facing.ditaval — and select the file. 

What args.filter does is reference the content filter in customer_facing.ditaval and tells the publishing engine to filter our content accordingly. So, when we publish the PDF and take a peek at it, we see only the content intended for external customers. 

Pretty neat, huh? This is a basic example of audience filtering. The capabilities of conditional processing are incredibly powerful, but one must start somewhere. 

For more in-depth information, we encourage you to read through our documentation on Context and Conditional Processing.

 

Tim Ludwig
Get a Demo
X