Managing re-use files

There are two different approaches to managing DITA content re-use files, used to store conref referenced source elements. The preferred approach is to store the elements centrally in a dedicated re-use topic.

DITA can re-use an existing document fragment (essentially, any element) from another topic through the conref feature. For example, a common warning needs only to be written once, and then can be re-used throughout a document suite. The conref source can either be left in the topic in which they happen to be first used, or moved to a dedicated re-usable content topic, whose only purpose is to store re-usable fragments.

In nearly all cases, the best approach is to store re-usable components in a dedicated re-use topic, in a common location. This is known as the centralised approach; referenced conref source fragments are stored in a single location.

The centralised strategy of using one or more files to hold elements that you want to re-use reduces dependencies. If you give a set of DITA topics to another writer, you only need to provide the set of topics plus the re-use file. You don't need to hunt around to find other topics that might contain re-used elements. The centralised strategy also simplifies the associations (linkages) between files.

You should assign file names prefixed with conref_ to topics that are only used as stores for re-use elements.

Figure 1. Example of conref source files within a conref folder

If you are using one conref source topic for all your re-use elements, use the ditabase information type for this purpose. This information type can contain both common elements and elements specific to different information types. For larger documentation repositories, you should organise your re-use elements into separate files for separate purposes, such as one file for warnings, one file for variables, one file for steps, and so on.

You should also make a practice of including the dedicated re-use topic(s) in the collection's ditamap, with the toc attribute set to no, the linking attribute to none, and the print attribute set to no. Including the re-use topic in the map provides a reminder that the collection uses that specific re-use topic, and to include the topic when sending the collection source files to another author. This is especially important for large repositories of information, or where your CMS uses the ditamap as a basis for copying or checking out files. If you have more than a handful of re-use topics, you should use a nested map to collect those re-use topics together, and then reference that map file in your collection's ditamap.

Note:

In DITA 1.2, a processing-role attribute was introduced to the topicref element. Setting the value of this attribute to resource-only is a better alternative to setting toc, linking and print attributes otherwise required for DITA 1.1. It also clearly identifies the referenced topic as simply a resource, and not explicitly part of the content.

Ideally, conref topics should be stored in their own folder at one directory level lower than the ditamap, or loosely in the same directory as the ditamap.