FLOWiki

(y)our wiki about all things technical communication

User Tools

Site Tools


dita:different_levels_of_content_re-use

Different levels of content re-use

Using content references (conrefs)

Content references (conrefs) are generally the smallest type of content re-use as you only reference a single element of your content. However, the size of the element may vary greatly from one word to an entire section.

You cannot conref loose bits of content; the text must always be embedded within its element tags. This is because text on its own cannot have an ID to reference, only elements can hold an ID. This also means you are bound by the DITA structure rules and need to re-use an element within its appropriate content. You cannot, for instance, conref a <step> element (used only in task topics) in a concept topic.

Re-using elements

On the smallest scale, you can reference a single word or phrase. This should be done with care, however, as conreffing these can lead to issues such as ungrammatical sentences. To avoid any issues, it is safest to stick to fixed nouns, names and phrases that are unlikely to be modified by grammar, such as:

Commonly re-used elements Examples
<cite> Titles of books
<filepath> File, directory or path names
<keyword> Product names, model numbers
<menucascade> and <uicontrol> Interface buttons, menus, check boxes, tabs
<wintitle> Names of windows, panels, pages or dialog boxes

On a larger scale, commonly referenced elements include:

  • Lists
  • Steps
  • Tables
  • Sentences
  • Paragraphs

Re-using topics

Re-using topics is a very good way of making efficient use of your content. When you write your content according to the best-practice suggestions, your topics will be clear and self-contained, meaning they can easily be re-used elsewhere and still make sense.

The main way you can re-use a topic is by inserting it into multiple DITA maps. This way you essentially have a single repository of topics, and you link the ones you need in the relevant DITA map(s).

There are types of topics that respond very well to being re-used like this, for instance:

  • Topics that contain standard text, such as legal information.
  • Topics with a recurring information set, such as a procedure that must be done in multiple task flows or scenarios.

Topics that need to appear in different sets of information. For example, when you need to add the same topic to a help system and to a PDF file for a user guide.

If you have a similar topic but with content that needs to be customized, you can create a DITA template instead. Writers can re-use that template to make similarly structured topics but with unique content.

Using the same topic several times in the same DITA map can create problems when generating output (all links to the topic will point to the first instance of the topic). If you need the same topic to appear several times in the same map, you should use the @copy-to attribute. You enter a new filename in the copy-to attribute of the <topicref> element. In this way, you create duplicate topic references in the DITA map without actually creating additional topics in the source files. You can then use the <linktext> and <shortdesc> elements in the <topicmeta> element of the topic reference to provide a unique title and short description to help you distinguish between the two in link previews.

Re-using DITA maps

You can re-use entire DITA maps in your structure. To create re-usable DITA maps, create and organize topics into submaps that document common features or user tasks. For example, even if you only have one user guide, you can create one DITA map for installation topics, one DITA map for security topics, and one DITA map for configuration topics.

Re-using content from non-DITA sources

You can re-use existing content such as product codes and external sources by automatically pulling it into your DITA topics. For example, instead of writing a programming reference guide from scratch, you might pull comments from the software code and use those comments in your DITA topics.

Because DITA is a semantic tagging language, it can easily map non-DITA content to the proper DITA elements and insert the content in the correct location in your DITA topics.

dita/different_levels_of_content_re-use.txt · Last modified: 2017/03/30 13:16 (external edit)