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.

Remember: By default, profiled content not specified in a DITAVAL is included in a deliverable.
Figure 1. Filtering Map Elements.

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”.

DITAVAL filtering diagram
Figure 2. Filtering Topic Elements.

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”.

DITAVAL filtering diagram

Conditional Processing Attributes

The DITA conditional processing attributes enable you to profile topic and map elements. You can then include or exclude profiled content during publication by using DITAVALs.

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”)
Note: If needed, we can configure conditional processing attribute specific to your organization. For more information, contact your Customer Success Manager.

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

Note: If you want to set default values for conditional processing attributes, do one of the following:
  • 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.

Figure 3. 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.

Attributes tab

Profiling Map Elements

You can profile map elements by using the Edit Properties window.

Figure 4. Edit Properties Window
Edit Properties Window

Audience Profiling

You can use the audience attribute to make content more reusable and publish customized deliverables.

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

You include or exclude profiled content by applying a DITAVAL during publication.
Remember: By default, profiled content not specified in a DITAVAL is included in a deliverable.
Figure 5. Internal Step Element.

The following example shows an internal step element (3). The step will not be included in the customer-facing documentation.

Figure 6. Internal Step Result Elements.

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.

Figure 7. Internal Topic.

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.

Figure 8. DITAVAL for Customer-Facing Documentation.

The following example shows a DITAVAL that excludes internal content in the customer-facing output.

Product Profiling

You can use the product attribute to make content more reusable and publish customized deliverables.

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

You include or exclude profiled content by applying a DITAVAL during publication.
Remember: By default, profiled content not specified in a DITAVAL is included in a deliverable.
Figure 9. Product-Specific Specification.

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”).

Figure 10. Product-Specific Topic.

The following example shows a task topic specific to “productA”.

Figure 11. DITAVAL for “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

You include or exclude profiled content by applying a DITAVAL during publication.
Remember: By default, profiled content not specified in a DITAVAL is included in a deliverable.
Figure 12. Platform-Specific Sections.

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.

Figure 13. Platform-Specific Topic.

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.

Figure 14. DITAVAL for Windows-Specific Documentation.

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

You include or exclude profiled content by applying a DITAVAL during publication.
Remember: By default, profiled content not specified in a DITAVAL is included in a deliverable.
Figure 15. Output-Specific Figures.

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.

Figure 16. Output-Specific Topic.

The following example shows the “Online Help Welcome Page” topic that is specific for online outputs.

Figure 17. DITAVAL for Online Documentation.

The following example shows a DITAVAL that includes online-specific content and excludes print-specific content.

DITAVALs

You use DITAVALs to include or exclude conditional content in deliverables. In other words, DITAVALs are files that contain rules for conditional publishing.

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.

  1. Develop content. See Develop Conditional Content.
  2. Apply conditional profiling by doing any of the following:
    • Profile topic elements. See Profile Topic Elements.
    • Profile map elements. See Profile Map Elements.
      Figure 18. Internal-OnlyTopic.

      The following example shows how to apply the @audience="internal" profiling attribute to a “Reference A” topic. Because this topic contains technical details that could be useful for the engineers employed by your company, itshould not be visible in customer-facing documentation.

      Filtering for internal audiences
      Figure 19. Output-Specific Topic.

      The following example shows the “Online Help Welcome Page” topic that is specific for online outputs.

  3. Create relevant DITAVALs. See Create a DITAVal.
    Remember: Ensure to create DITAVALs for all the conditions you're using.
  4. Publish content with each DITAVAL that you created in 3. See Develop Conditional Content.
    Important: Your publishing scenarios may need to be configured to enable you to select DITAVALs for publications. If there is no args.filter or ditaval option in the publishing scenario that you want to use, contact your Heretto CCMS Administrator or Customer Success Manager.
Ensure that the content is filtered as expected in each deliverable by opening and inspecting the deliverables.