How do you apply filtering conditions to DITA maps and topics?

November 10, 2023
|By Bryan Tipper

In DITA, attributes play a significant role in content filtering. The most commonly used attribute for filtering is audience. However, organizations can create their own custom attributes to suit their specific needs. These attributes can represent various criteria, such as audience segments (beginners, experts, administrators), product versions, languages, or any other context that requires content differentiation.

DITA Maps and Filtering Criteria

The central document for managing filtering conditions is the DITA map. In the map, criteria is defined for filtering based on these attributes. Think of the DITA map as a blueprint for generating different versions of the documentation, each tailored to a specific audience or purpose.

Filtering Mechanism in Publishing

The filtering process typically occurs during the publishing or output generation phase. Publishing systems and tools are configured to recognize the attributes and criteria defined in the DITA map. When generating output, these tools select the appropriate profile or audience criteria.

For example, when producing a user guide for beginners, the publishing system recognizes the audience=”beginner” attribute and includes only the “getting-started” topic, providing content relevant to beginners.

Content Reuse and Conref

Filtering can also involve content reuse using mechanisms like “conref” (content reference). This is useful for managing overlapping content across different audiences or outputs. Conref enables referencing content from one topic within another while still respecting the filtering criteria. This way, a single source is maintained for the shared content, making updates easier to manage.

Advanced Filtering with Elements

Beyond attributes, DITA provides elements like <keyword>, <props>, and <conaction>, which can be used for more complex filtering conditions. These elements add another layer of granularity to the filtering process. For example, <keyword> elements allow for tagging topics with keywords that can be included or excluded in specific outputs based on these tags.

Example

An organization is documenting a versatile software application that works on multiple platforms. The troubleshooting section is common across platforms, but each platform requires specific troubleshooting steps. They want to ensure that only the relevant troubleshooting information appears in the documentation for each platform.

<map>
  <title>Software Troubleshooting Guide</title>
  <topicref href="common-troubleshooting.dita" platform="common"/>
  <topicref href="windows-troubleshooting.dita" platform="windows"/>
  <topicref href="mac-troubleshooting.dita" platform="mac"/>
  <topicref href="linux-troubleshooting.dita" platform="linux"/>
</map>

This DITA map contains topics specific to different platforms, and each topic includes a platform attribute that indicates which platform it relates to.

Content Tagging

The “common-troubleshooting.dita” makes use of content tagging elements and attributes.

<topic id="common-troubleshooting">
  <title>Common Troubleshooting</title>
  <body>
    <ul>
      <li>>Issue 1: <keyword>Connection Problems</keyword></li>
      <li>>Issue 2: <keyword>Performance Slowdown</keyword></li>
      <!-- Common troubleshooting content -->
    </ul>
  </body>
</topic>

In this topic, issues have been tagged with <keyword> elements that provide additional context for filtering. Each issue is associated with a keyword, which helps the filtering mechanism decide what content to include based on the platform attribute.

Filtering Configuration

When generating documentation for a specific platform, the publishing system recognizes the platform attribute in the DITA map. For example, when producing documentation for the Windows platform, the system would select the “windows-troubleshooting.dita” topic. It also considers the keywords associated with issues to include only those issues relevant to Windows troubleshooting.

Output

The resulting documentation output for the Windows platform will display the “Common Troubleshooting” topic with Windows-specific troubleshooting steps:

<topic id="common-troubleshooting">
  <title>Common Troubleshooting</title>
  <body>
    <ul>
      <li>>Issue 1: <keyword>Connection Problems</keyword> (Windows-specific steps)</li>
      <!-- Windows-specific troubleshooting content -->
    </ul>
  </body>
</topic>

In this way, the DITA-based documentation system dynamically assembles content based on the platform, ensuring that users receive platform-specific troubleshooting guidance.