Reuse Strategies

You can use the same source content in multiple topics or maps. This way, in case of updates, you only need to edit the source content.

Reuse Mechanisms

easyDITA enables you to leverage every DITA reuse mechanism.

Leveraging DITA reuse mechanisms enables you to:

  • Boost consistency in your documentation
  • Save time while updating and maintaining content
  • Quickly update variable data

Component Reuse

You can reuse topics and maps by adding them to multiple maps.

Overview

You reuse topics and maps by using topicref elements and mapref elements to insert that component into a map.

Figure 1. Component Reuse Operation.
The following diagram illustrates that:
  • “Topic A” is reused in “Map A” and “Map B”
  • “Topic B” is reused in “Map A” and “Map C”
  • “Map D” is reused in “Map B” and “Map C”
Tip: You can view detailed reuse information about every file in easyDITA by right-clicking a file and selecting Links . The Links tab shows incoming links, outgoing links, or all file dependencies.

Example

The following example shows the behavior of the topic and map reuse indicator in the content library when you reference a file in your map.
Note: When the indicator is black, that means the component is used in a map somewhere within the content library. When the indicator is green, that means the component is reused in the currently opened map. The number indicates how many times the component is globally reused.
Figure 2. Map A
Figure 3. Map B
Figure 4. Map C

Element Reuse

You can reuse topic elements including steps, paragraphs, notes, figures, lists, sections, and more.

Overview

You reuse topic elements by using content references (conref attributes).

Figure 5. Element Reuse Operation.
The following example shows that:
  • “Element B” is reused in “Topic A” and “Topic B”
  • “Element C” is reused in “Topic B” and “Topic C”
Tip: You can view detailed reuse information about every file in easyDITA by right-clicking a file and selecting Links . The Links tab shows incoming links, outgoing links, or all file dependencies.

Example

The following examples show the element reuse mechanism in easyDITA. The topic editor indicates reused elements with a gray background in the target topic.

Figure 6. Element Warehouse Topic.

The following example shows a warehouse topic that includes two reusable topic elements (“Element B” and “Element C”). Each of these elements has an unique @ID attribute assigned. The unique @ID attributes enable you to reuse these elements.

Tip: easyDITA includes a reuse indicator that enables you to quickly check and navigate to the resource where an element is reused.
Figure 7. Topic A.

In the following example, “Element B” is reused from a “Warehouse Topic”.

Figure 8. Topic B.

In the following example, “Element B” and “Element C” are reused from a “Warehouse Topic”.

Figure 9. Topic C.

In the following example, “Element C” is reused from the “Warehouse Topic”.

Localization Considerations

If you localize content or plan to localize content, keep the following considerations in mind while reusing elements:

  • You can reuse the following types of elements:
    • Block elements (for example, section elements, paragraph elements, or note elements)
    • Inline elements (for example window title elements, UI control elements, or phrase elements)
  • Reusing inline elements may make your content difficult to localize because sentence structure can vary from language to language. Reused inline elements created in one language may cause grammatical errors in other languages.
  • Reusing block elements is safer than reusing inline elements. However, you should still pay attention to the context in which you reuse block elements.

Variable Reuse

Variables enable you to easily reuse and update content like a product names, interface terms, or other items that might change either because they're being used in different contexts or because of external changes like rebranding.

Variable Reuse Methods

You can reuse variables by using conkeyref attributes or keyref attributes. However, we recommend reusing variables with conkeyref attributes. Whatever method you choose, use it consistently.

Table 1. Variable Reuse Methods Comparison
Variable Reuse with ConkeyrefsVariable Reuse with Keyrefs
Can be fully managed through a dedicated graphical user interface in easyDITA.Cannot be fully managed through a dedicated graphical user interface in easyDITA. You may need to use the source editor to edit DITA code.
Contained in variable warehouse topics.Contained in variable warehouse maps.
Involves conkeyref attributes.Involves keyref attributes.
Involves phrase elements.Involves keyword elements.

Localization Considerations

If you localize content or plan to localize content, keep the following considerations in mind while using variables:

  • In some languages, words change form depending on their role in the sentence. Because the text in the variables forms a part of the grammatical structure of the sentence, using a variable in sentences with different grammatical structures can introduce unintended errors in the target language.
  • You can safely use non-grammatical items for variable content. For example, it is rather safe to translate variable content like phone numbers, addresses, hours of operation, or external links.

Variable Reuse with Conkeyrefs

You reuse variables from variable warehouse topics with conkeyref attributes.

Overview
The following example shows that:
  • The “Variables Warehouse” topic is added to the deliverable “Map A” through the keydef element with the @keys attribute assigned.
    Important: Including variable warehouse topics through the keydef element with the @keys attribute assigned is necessary for the variable reuse mechanism to operate properly. By default, keydef elements are not included in the output.
  • “Variable A” is used in “Element A” in “Topic A”.
  • “Variable B” is used in “Element A” and in “Element D”. The elements are in different topics.
Example

The following examples show the variable reuse mechanism through conkeyref attributes in easyDITA. The topic editor indicates reused variables with gray background.

Figure 10. Map A.

The following example shows a map that includes “Topic A”, “Topic B” and “Warehouse Topic”. The warehouse topic contains variables.

<map id="ditamap-7326" title="Map A">
    <topicref href="topic_a.dita"/>
    <topicref href="topic_b.dita"/>
    <keydef href="warehouse_topic.dita" keys="vars"/>
</map>
Figure 11. Variable Warehouse Topic.

The following example shows a warehouse topic that includes two variables.

Figure 12. Topic A.

The following example shows a topic that references two variables from the variable warehouse topic.

Figure 13. Topic B.

The following example shows a topic that references one variable from the variable warehouse topic.

Variable Reuse with Keyrefs

You can reuse variables from variable warehouse maps with keyref attributes.

Overview
The following example shows that:
  • The “Warehouse Map” is added to the deliverable “Map A” through the mapref element with the @processing-role="resource-only" attribute assigned.
  • “Variable A” is used in “Element A” in “Topic A”.
  • “Variable B” is used in “Element A” and in the “Element D”. The elements are in different topics.
Example

The following example shows the variable reuse mechanism through keyref attributes in easyDITA. The topic editor indicates reused variables with gray background.

Figure 14. Variable Reuse Example.
The following example shows that:
  • The “companyName” variable is used in “Topic A”
  • The “productName” variable is used in “Topic A” and “Topic B”
  • The variables are reused from “Variable Warehouse Map” through keyref attributes and keyword elements

Warehouses

Warehouse topics and warehouse maps enable you to keep reusable content in a central location.

Remember: Large warehouse topics and warehouse maps are difficult to maintain and may negatively affect the editing performance. We recommend to create small and specific warehouses with content growth in mind.

Element Warehouse Topics

Element warehouse topics contain topic elements that you can reuse through the @conref attribute.

Single-Sourcing Elements

We recommend keeping reusable elements centralized in warehouse topics. This way, you can easily find and maintain such elements.

Figure 15. Good Practice: Elements Reused from a Single Source.
The following example illustrates that:
  • The reusable “Element A” and “Element B” are in the “Elements Warehouse” topic that enables single-sourcing
  • “Element A” is reused in “Topic A”. “Topic B”, and “Topic C”
  • “Element B” is reused in “Topic A”, “Topic B”, and “Topic C”
Figure 16. Bad Practice: Spaghetti Reuse of Elements.
The following example illustrates that:
  • There is no warehouse topic so the reusable elements are not kept in a central location
  • “Topic B” and “Topic C” reuse “Element A” from “Topic A”
  • “Topic A” and “Topic C” reuse “Element B” from “Topic B”
Important: The example illustrates a bad practice! The result is similar as in the Good Practice: Elements Reused from a Single Source example but the file dependencies are much more complicated. Such a reuse web is hard to maintain.

Multiple Elements Warehouse Topics

Creating separate warehouse topics for specific kinds of reusable content enables you to make its management easier. The following examples illustrate that this is a scalable approach.

Figure 17. Information-Type-Specific Warehouses.

In the following example, each of the warehouse topics contains content related to a given topic type. This approach is sufficient if you maintain a limited amount of documentation. Maintaining a large variable set may slow down variables processing and makes it difficult to search for variables.

Figure 18. Content-Specific Warehouses.
The following example illustrates that the:
  • “Installation Steps Warehouse” task topic contains installation-related steps
  • “Operation Steps Warehouse” task topic contains operation-related steps
  • “Specifications Warehouse” reference topic contains tables with specifications
  • “Safety Notes Warehouse” concept topic contains safety precautions
  • “Tip Notes Warehouse” concept topic contains tips

This approach is recommended if you maintain a large amount of documentation.

Guidelines

Keep the following guidelines in mind when working with warehouse topics:

  • Keep the element warehouse topics in a dedicated folder in the content library. For example, keep them in the _shared folder.
  • Add the element warehouse topics to the shared map. For more information, see Shared Map.
  • Consider assigning meaningful @ID attributes to the reusable elements. For example, note_electrocution_warning or step_install_windows
    Important: Assigning unique @ID attributes to the reusable elements is necessary to reuse these elements through the @conref attribute.

Variable Warehouse Topics

Variable warehouse topics contain variable content that you can reuse through the @conkeyref attribute.

Number of Variables Warehouse Topics

Depending on the size of your documentation set and the amount of the variables that you use in it, you can either create a single variable warehouse topic or multiple variable warehouse topics.

Figure 19. Single Variable Warehouse.

The following example illustrates a single variable warehouse topic that contains variables of different categories. This approach is sufficient if you maintain a limited amount of documentation. Maintaining a large variable set may slow down variables processing and makes it difficult to search for variables.

Figure 20. Multiple Variable Warehouses.

The following example illustrates the same variables as in Single Variable Warehouse divided into content-specific variable warehouse topics.

This approach is recommended if you maintain a large amount of documentation.

Global Variables Strategy

You can include variable warehouse topics in a shared map so that they are available in every deliverable map that you create in easyDITA. For more information, see Shared Map.

Context-Specific Variables Strategy

Using context-specific variables enables you to reuse more topics.

Figure 21. Content-Specific Variable Warehouses.
The following example illustrates that:
  • The “Classic Variables Warehouse” topic is added to the “Classic Toaster” map
  • The “Lightning Variables Warehouse” topic is added to the “Lightning Toaster” map
  • Both maps reuse the following topics:
    • <ph conkeyref="vars/product_name"/> Overview
    • Safety Notes from <ph conkeyref="vars/company_name"/>
    • Toasting Brad with <ph conkeyref="vars/product_name"/>
    Note: The reused topics reference variables so that they fit in different contexts.

    This example illustrates that variables were used in topic titles. Remember that you can use variables in other topic elements (for example, step elements or note elements).

  • The Defrosting Bread with <ph conkeyref="vars/product_name"/> topic is used only in the “Lightning Toaster” map

Guidelines

Keep the following guidelines in mind when working with variable warehouse topics:

  • Keep the variable warehouse topics in a dedicated folder in the content library. For example, keep them in the _shared folder.
  • Assign meaningful and consistent IDs to the variables. This way, each author will be able to easily search for and topic editor.

    For example, you can assign the following IDs: product_a_name, company_name, or admin_interface.

Variable Warehouse Maps

Variable warehouse maps contain variable content that you can reuse through keyword elements and keyref attributes.

Number of Variables Warehouse Maps

Depending on the size of your documentation set and the amount of the variables that you use in it, you can either create a single variable warehouse map or multiple variable warehouse maps.

Figure 22. Single Variable Warehouse Map.

The following example illustrates a single variable warehouse map that contains variables of different categories. This approach is sufficient if you maintain a limited amount of documentation. Maintaining a large variable set may slow down variables processing and makes it difficult to search for variables.

Global Variables Strategy

You can include variable warehouse maps in the global shared map so that they are available in every deliverable map that you create in easyDITA. For more information, see Shared Map.

Figure 23. Multiple Variable Warehouse Maps.

The following example illustrates the same variables as in Single Variable Warehouse Map divided into content-specific variable warehouse maps.

This approach is recommended if you maintain a large amount of documentation.

Context-Specific Variables Strategy

Using content-specific variables enables you to reuse more topics.

Figure 24. Context-Specific Variable Warehouses.
The following example illustrates that:
  • The “Classic Variables Warehouse” map is added to the “Classic Toaster” map
  • The “Lightning Variables Warehouse” map is added to the “Lightning Toaster” map
  • Both maps reuse the following topics:
    • <keyword keyref="vars/product_name"/> Overview
    • Safety Notes from <keyword keyref="vars/company_name"/>
    • Toasting Bread with <keyword keyref="vars/product_name"/>
  • The Defrosting Bread with <keyword keyref="vars/product_name"/> topic is used only in the “Lightning Toaster” map

Guidelines

Keep the following guidelines in mind when working with variable warehouse maps:

  • Keep the variable warehouse maps in a dedicated folder in the content library. For example, keep them in the _shared folder.
  • Assign meaningful and consistent @keys attribute values to the variables. This way, each author will be able to easily add a variable in the topic editor.

    For example, you can assign the following @keys attributes: product_a_name, company_name, or admin_interface.

Shared Map

Shared maps enable you to easily add every warehouse topic to the deliverable maps.

Overview

Shared maps ease the effort needed to reuse content because you don't need to manually add all warehouse resources to each map.

Figure 25. Shared Map Structure.
The following example shows that:
  • Element warehouses are added to maps through topicref elements
  • Variable warehouses are added to maps through keydef elements with a @keys attribute assigned
Figure 26. Shared Map Implementation.

The following example shows a shared map reused in two deliverable maps. The shared map reference in the deliverable map has the @processing-role="resource-only" attribute assigned to exclude the shared content from the deliverable map's publishes.

Guidelines

Keep the following guidelines in mind when working with shared maps:

  • Use a singular shared map.
  • Keep the shared map and the warehouse map in a dedicated folder in the content library. For example, keep them in the _shared folder.
  • Include every warehouse topic in the shared map.
    Important: This does not apply to the “Context-Specific Variables Strategy” described in Variable Warehouse Topics.
  • Add the shared map to every deliverable map with the @processing-role="resource-only" attribute.
    Tip: We can configure your shared map to be included in every new map that you create in easyDITA by updating your map templates. For more information, contact you Customer Success Manager.

Develop Reusable Elements and Variables

Develop reusable topic elements and variables in dedicated warehouse topics.

Before you begin, to develop and reuse components in the deliverable maps. See Reuse Components in the Topic Editor.
Tip: The simplest way to reuse content is to create topics that are generic enough to fit different contexts and specific enough to be informative in each of these contexts.

If needed, you can profile elements in topics to make the topics relevant in multiple contexts. For more information, see Conditional Processing Strategies.

Figure 27. Component Reuse Operation.
The following diagram illustrates that:
  • “Topic A” is reused in “Map A” and “Map B”
  • “Topic B” is reused in “Map A” and “Map C”
  • “Map D” is reused in “Map B” and “Map C”
  1. In the content library, create a folder for the warehouse topics. See Create a Folder.
    For more information on the content organization in the content library, see Content Organization Strategies.
  2. Create relevant element and variable warehouse topics. See Create a Topic.
    Warehouse topics enable you to store reusable content in a single source.
  3. Develop reusable content in the warehouse topics. See Add Reusable Elements to Warehouse Topics and Create a Variable Warehouse Topic.
    Note: Reusable content should be generic enough to fit different contexts and specific enough to be helpful in each of these contexts.

    If needed, you can profile reusable content to make the content relevant in multiple contexts. For more information, see Conditional Processing Strategies.

    Figure 28. Element Warehouse Topic.

    The following example shows a warehouse topic that includes two reusable topic elements (“Element B” and “Element C”). Each of these elements has an unique @ID attribute assigned. The unique @ID attributes enable you to reuse these elements.

    Tip: easyDITA includes a reuse indicator that enables you to quickly check and navigate to the resource where an element is reused.
    Figure 29. Variable Warehouse Topic.

    The following example shows a warehouse topic that includes two variables.

  4. Create a shared map. See Create a Map.
    Shared maps include warehouse topics with reusable content.
  5. Add the warehouse topics to the shared map. See Add Reusable Elements to Warehouse Topics and Create a Variable Warehouse Topic.
    The shared map enables you to keep the warehouse topics in a central location.
  6. Include the reusable content in the deliverable maps by doing the following:
    1. Add the shared map to the deliverable map. See Reuse Components in the Topic Editor.
    2. On the shared map mapref element, set the processing-role attribute to resource-only. See Edit Topic Element Attributes.
    Tip: We can configure your shared map to be included in every new map that you create in easyDITA by updating your map templates. For more information, contact you Customer Success Manager.
  7. Reuse content in different assets by doing any of the following: