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”
Single-sourcing elements
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.
Bad practice: spaghetti element reuse

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.

Information-type-specific warehouses
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.

Content-specific warehouses

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.