Your Account
avatar photo

guest

Logout
User GuideContent StrategieseasyDITA GuidesDITA GuidesFAQsRelease Details
contact support
Loading...
  • Contents
  • Reuse
  • Overview
    • Component Reuse
    • Element Reuse
    • Variable Reuse
  • Warehouse Topics
    • Element Warehouse Topics
    • Variable Warehouse Topics
  • Shared Map
  • Develop Reusable Elements and Variables
Strategies > Reuse
send feedback
❮   Previous Next   ❯
  • Contents
  • Reuse
  • Overview
    • Component Reuse
    • Element Reuse
    • Variable Reuse
  • Warehouse Topics
    • Element Warehouse Topics
    • Variable Warehouse Topics
  • Shared Map
  • Develop Reusable Elements and Variables
Reuse Strategies

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

Reuse Mechanisms

easyDITA enables you to leverage every DITA reuse mechanism.

Leveraging the DITA reuse mechanisms enables you to:

  • Boost consistency in your documentation
  • Save time while updating and maintaining content
  • Quickly update variable data like company name or product name
Component Reuse

Component Reuse

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

Overview

You reuse topics and maps through topicref elements and mapref elements.

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”

Example

The following example shows the topic and map reuse indicator in the content library.
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

Element Reuse

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

Overview

You reuse topic elements through content references (conref attributes).

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

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 2. 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 3. Topic A.

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

Figure 4. Topic B.

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

Figure 5. 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)
    Note: For detailed information on the block elements and inline elements, Technical Content Development Guidesee Topic 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

Variable Reuse

Variables enable you to easily reuse and update content like a product name, your company name, or interface elements nomenclature.

Overview

You reuse variables through conkeyref attributes.

Figure 1. Variable Reuse Operation.
The following example shows that:
  • The “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 the “Element A” and in the “Element D”. The elements are in different topics.

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.

Example

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

Figure 2. 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 3. Variable Warehouse Topic.

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

Figure 4. Topic A.

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

Figure 5. Topic B.

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

Warehouse Topics

Warehouse Topics

Warehouse topics enable you to keep reusable content in a central location.
Element Warehouse Topics

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 1. 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 2. 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 3. 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 4. 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

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 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 1. Single Variable Warehouses.

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 2. Multiple Variable Warehouses.

The following example illustrates the same variables as in Single Variable Warehouses 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 the global 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 content-specific variables enables you to reuse more topics.

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

  • 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 add a variable in the topic editor.

Shared Map

Shared Map

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

Overview

Figure 1. 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 2. 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 maps 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 Elements and Variables

Develop reusable topic elements and variables in dedicated warehouse topics.

Before you begin, try to develop and reuse components in the deliverable maps. User GuideSee 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 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”

  1. In the content library, create a folder for the warehouse topics. User GuideSee 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. User GuideSee Create a Topic.
    Warehouse topics enable you to store reusable content in a single source.
  3. Develop reusable content in the warehouse topics. User GuideSee Add Reusable Elements to Warehouse Topics and Add Variables to Variable Topics.
    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 2. 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 3. Variable Warehouse Topic.

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

  4. Create a shared map. User GuideSee Create a Map.
    Shared maps include warehouse topics with reusable content.
  5. Add the warehouse topics to the shared map. User GuideSee Add Reusable Elements to Warehouse Topics and Add Variables to Variable Topics.
    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. User GuideSee Reuse Components in the Topic Editor.
    2. On the shared map mapref element, set the processing-role attribute to resource-only. User GuideSee 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:
    • Reuse topic elements. User GuideSee Reuse Elements from Warehouse Topics.
    • Reuse variables User GuideSee Reuse Variables in Topics.
Loading...

There was a problem loading this topic

  • Jorsek LLC

    320 Goodman St. N.
    Suite 104
    Rochester, NY 14607
    USA
    Toll Free: 1-877-492-2960

  • Additional Resources

    • easydita.com
    • About
    • Resources
    • Support
Copyright © 2004-2017 Jorsek LLC. | Legal

Add/Remove Bookmark Sets