How do I manage content variants in DITA?

Managing content variants in DITA involves handling different versions or variations of content within your documentation. This is crucial for providing tailored information to diverse audiences, addressing product versions, or offering content in multiple languages. DITA offers mechanisms like conditional processing, keys, and profiling to manage content variants efficiently.

Managing content variants in DITA is essential to create documentation that caters to different audiences, product versions, languages, or other specific needs. The core DITA functions for managing content variants are:

  • Conditional Processing: DITA allows conditionally including or excluding content based on specified criteria. This is useful for creating variant documents for different user segments. For example, conditional tags can be used to include content specific to beginners, intermediates, or experts in a user guide.
  • Keys and Key References: DITA keys and key references provide a way to dynamically retrieve and display content based on key values. This is valuable for content that varies depending on factors like product versions or language preferences. Keys can be assigned values in maps or topics, and key references retrieve content matching these values.
  • Profiling: Profiling involves tagging content with attributes to categorize it. This can be used to distinguish content meant for different purposes or audiences. For example, content may be profiled as “beginner,” “intermediate,” or “advanced” and then included or excluded accordingly.
  • DITAVAL Files: DITAVAL files are used to define conditions and criteria for conditional processing. They specify which content variants should be included or excluded during publishing or transformation. DITAVAL files provide a structured way to manage content variations.


This example software user guide needs to provide instructions for three different versions of the software (Version A, Version B, and Version C). Additionally, there are two user segments: beginners and advanced users. Here’s how content variants can be managed:

  • Conditional Processing: Using conditional tags, sections are marked as relevant to Version A, Version B, or Version C. For instance, content tagged with <product-version product=”A”> is intended for users of Version A.
  • Keys and Key References: Keys like software-version are created and assigned values like “A,” “B,” or “C” in the map or topic references. Then, in the content, key references like <conkeyref keyref=”software-version”/> are used to pull in the appropriate content based on the software version specified in the map.
  • Profiling: Profile content with attributes such as audience=”beginner” or audience=”advanced”. This allows inclusion or exclusion of content segments in the output based on the user’s expertise level.