Conditional Processing Strategies
Conditional processing enables you to publish customized deliverables for specific audiences and reuse more content.
Conditional Processing Overview
You develop conditional content by profiling topic and map elements with specific attributes and applying DITAVAL filtering during publication.
In the following example, “Topic C” is profiled with the
@audience="internal"
attribute because it contains internal-only content. At publish, a DITAVAL excludes internal content from the
deliverable. In consequence, the deliverable does not contain “Topic
C”.
In the following example, “Element B” is profiled with the
@platform="windows"
attribute because it contains
Windows-specific content. “Element C” is profiled with the
@platform="macos"
because it contains macOS-specific
content. At publish, a DITAVAL includes
windows-specific content and excludes macOS-specific content from the
deliverable. In consequence, the deliverable does not contain “Element
C”.
Conditional Processing Attributes
Attributes and Values
You can assign any of the following default conditional processing attributes to topic and map elements:
- audience attribute
- platform attribute
- product attribute
- otherprops attribute (“otherprops” stands for “other properties”)
By default, the conditional processing attributes can take any value. For example, you can set the platform attribute value to “Windows”, “macOS”, or anything else. The values are case-sensitive so, for example, “MacOS” is a different value than “macOS”, and in Heretto CCMS you use a space to separate two values. We recommend using underscores if you need a single value but want to use multiple terms
- Set the attribute values by using a special kind of taxonomy. See Taxonomy-Driven Attributes.
- Contact your Customer Success Manager.
Setting default values for conditional processing attributes ensures that every author profiles content in a consistent way.
Profiling Topic Elements
You can profile topic elements by using the Attributes tab.
The list of attributes that shows is context-sensitive. By default, the list contains attributes that are available to apply to the element where your cursor is located.
Profiling Map Elements
You can profile map elements by using the Edit Properties window.
Audience Profiling
Use Cases
Consider profiling your content with the audience attribute in the following scenarios:
- Your customers use the same product but have different features enabled. This way, each customer can get personalized documentation that covers only relevant features.
- You want to provide content that is applicable to different roles in your product. For example, users with Administrator roles may need system configuration information, but users with Reviewer role do not.
- You want to include internal-only content in the documentation set. The internal content can be hidden from the customer-facing deliverables and included in the internal documents.Tip: Internal content in the documentation can be used by your quality assurance teams for tests or provide restricted information for your technicians.
Audience Profiling Example
The following example shows an internal step element (3). The step will not be included in the customer-facing documentation.
The following example shows internal step result elements. This way, the profiled elements will be included in the internal documentation for the quality assurance team but will not be included in the customer-facing documentation.
The following example shows an internal reference topic. The “Reference A” topic will be included in the internal documentation for the field engineers but will not be included in the customer-facing documentation.
The following example shows a DITAVAL that excludes internal content in the customer-facing output.
Product Profiling
Use Cases
Consider profiling your content with the product attribute in the following scenarios:
- You want to maintain a single set of documentation for multiple products that are similar
- You want to keep specifications for different products in one topic
Product Profiling Example
The following example shows a reference topic that contains specifications for “productA” and “productB”. The values of “Specification C” are different for “productA” (“ValueA”) and “productB” (“ValueB”).
The following example shows a task topic specific to “productA”.
The following example shows a DITAVAL that excludes “productB”-related content and includes “productA”-related content.
Platform Profiling
You can use the platform attribute to make content more reusable and publish customized deliverables.
Use Cases
Consider profiling your content with the platform attribute in the following scenarios:
- A product has steps or considerations specific to different operating systems. For example, the installation procedure of the product is different for macOS or Windows.
- A product operates differently on specific hardware platforms.
Platform Profiling Example
The following example shows a concept topic that contains sections specific to different operating systems. This way, the documentation for Windows users will exclude the macOS-specific content and the documentation for macOS users will exclude the Windows-specific content.
The following example shows a reference topic specific for Windows OS users. This way, the topic will be included in the documentation for Windows users but will not be included in the documentation for macOS users.
The following example shows a DITAVAL that includes Windows-specific content and excludes macOS-specific content.
Otherprops Profiling
You can use the otherprops attribute to make content more reusable and publish customized deliverables.
Guidelines
Consider profiling your content with the otherprops attribute in the following scenarios:
- You want to profile content but none of the conditional processing attributes seems suitable
- Your documentation is published to different outputs that may require different structure or may include slightly different content
Otherprops Profiling Example
The following example shows a “Figure A” element that includes a PNG image for printed outputs and a “Figure B” element that includes a GIF image for online outputs.
The following example shows the “Online Help Welcome Page” topic that is specific for online outputs.
The following example shows a DITAVAL that includes online-specific content and excludes print-specific content.
DITAVALs
Attributes
The action attribute enables you to process profiled content in the following ways:
- include
- Includes content in the output.
- exclude
- Excludes content from the output.
- passthrough
- Includes content in the output and preserves the attribute value for further processing. This may be useful for some outputs that include a filtering functionality.
- flag
- Includes and flags content in the output.
Operation
By default, conditional content is processed in the following way:
- Content that does not have a conditional profiling attribute assigned is included in the deliverable.
The default behavior of conditional profiling is to include content, so if you have only one condition, use only an exclude rule.
- Conditions cannot be nested. Parent conditional elements take precedence over children conditional elements.
Guidelines
Keep the following guidelines when working with DITAVALs:
- You can create generic DITAVAL files that apply to any map. We
recommend using generic DITAVALs if there is not much
conditional content in your documentation.
Examples: customer_facing_online or internal_print.
- You can create DITAVAL files that apply only to specific maps. We
recommend using map-specific DITAVALs if there is a lot of
conditional content in your documentation.
Examples: map_title_customer_facing or map_title_internal_print.
- Establish a DITAVAL naming convention to ensure that everyone in your organization can easily find and identify DITAVALs.
- Create DITAVALs for all conditional profiles to ensure that you do not accidentally publish content that you want to filter out.
Apply conditions in the context of the deliverable or target map, rather than on content in a library or warehouse file.
Keep the maintenance of conditional profiling in mind as you apply conditions. For example, apply conditions to entire steps or paragraphs instead of words. If you need different terms in different contexts, consider using keys instead of conditional profiling.
Develop Conditional Content
You can publish deliverables for different audiences by applying conditional processing attributes to the DITA content and filtering it with DITAVALs during publication.