DITA and reuse

Overview

DITA provides features that allow you to use text in multiple contexts. Reusing text (single sourcing) allows you to author something once and deploy it in multiple places

Some methods for reuse include:

• Conditional processing – You can selectively filter content in and out of maps and topics by applying metadata values. Doing so lets alter the content to fit the current content.
• Content references – You can share the content of an element into multiple topics.
• Topic and map reuse – You can use the same topic or map in multiple deliverables.

Conditional processing attributes

Conditional processing attributes allow you to filter the content in a topic based on metadata that you enter. It enables the reuse of the same topic in multiple contexts (single-sourcing)

For example, assume that you have two versions of a cellphone. One cellphone has more screen icons than the other phone. In a reference topic, you could  apply conditional processing values to the icons to the more feature-rich phones to identify the model. Doing so would allow you to document all of the icons in one file and to share the definitions for the icons that both phones have. However, you could filter out the unique icons from the user guide for the simpler cellphone when publishing the output.

DITA supports the following conditional processing attributes for filtering content:

• audience – Identifies the audience for the tagged text (such as installers, programmers, novice users, expert users and so on)
• platform – Identifies operating systems (such as Windows or Linux)
• product – Identifies product or component
• props – Acts as generic attribute (used to extend DITA)
• otherprops – Includes miscellaneous values that do not fit in the other categories

Examples:

<p product=“MyProduct”>This product….</p>
<step audience=“expert”><cmd>Do  this</cmd></step>        

Define the conditional processing values that you want to use up front.

For example, you might identify relevant audiences and product models for your cellphone documentation:

You do not need to use all conditional processing attributes for a single element.

Example

Assume that you have a definition list of icons with different product attributes applied, depending on the model of the product to which the icon applies.

<dl>
   <dlentry product="modelA modelB"> 
      <dt>Icon 1</dt> 
      <dd><p>description of icon 1</p></dd> 
  </dlentry> 
  <dlentry product="modelA modelB"> 
     <dt>Icon 2</dt> 
     <dd><p>Description of icon 2</p></dd> 
  </dlentry> 
  <dlentry product="modelB"> 
     <dt>Icon 3</dt> 
     <dd><p>Description of icon 3</p></dd> 
  </dlentry> 
  <dlentry product="modelA"> 
     <dt>Icon 4</dt> 
     <dd><p>Description of icon 4</p></dd> 
  </dlentry> 
  <dlentry> 
     <dt>Icon 5</dt> 
     <dd><p>Description of icon 5</p></dd> 
  </dlentry> 
</dl>

In this example, you can see:

• Multiple conditions – more than one value for an attribute. If either value is true, the content is included in output.

  <p product=“modelA modelB”>This paragraph…</p> 

• Compound condition – more than one attribute applied to the element. If either of the values is false, the content is not included.

  <step audience=“expert” product=“modelA”><cmd>Do this..</cmd></step>

Process for using conditional processing in oXygen

1. Define the attribute values that you want to use
2. Set your content to use the appropriate conditional processing attributes:
   • Apply conditional processing attributes to maps to filter out entire topics from a deliverable
   • Apply conditional processing attributes within topics to filter out elements from within a topic.
3. Create condition sets that define which conditions to include during publication
4. Apply the condition set
5. Publish your deliverable

Note: Creating a condition set is how oXygen defines the equivalent of the DITAVAL file. The DITAVAL file is described in detail in the Best Practices book.

Defining the values that you want to use

1. Select DITA > Profiling / Conditional Text > Configure Profiling Condition Sets.
2. In the Preferences window, select the attribute for which you want to specify values and click Edit.
   
3. In the Profiling Attribute window, click New.
4. In the Add window, enter the value that you want to add and click OK.
   Attribute values must be a single word and cannot contain spaces.
5. Repeat steps 3 and 4 for all values that you need to add.
6. When finished adding values, click OK.
7. On the Preferences window, ensure that Project Options is selected and click OK.

Setting conditional processing attributes within topics

1. Position your cursor within the element for which you want to set conditional processing values.
2. Select DITA > Profiling / Conditional Text > Edit Profiling Attributes.
   
3. In the Edit Profiling Attributes window, select the values that you want to specify and click OK.

Setting conditional processing attributes on maps

1. Open your DITA map.
2. Highlight the <topicref> element for the topic to which you want to apply attributes.
3. Select DITA > Profiling / Conditional Text > Edit Profiling Attributes.
4. In The Edit Profiling Attributes window, select the attributes that you want to use and click OK.

Creating a condition set for publishing

1. Select DITA > Profiling / Conditional Text > Configure Profiling Condition Sets.
2. Under Profiling Condition Sets, click New.
   
3. In the Condition Set window, name your condition.
4. Select the values that you want to apply to this deliverable.
5. Click OK.

Publishing using the condition set

1. Select DITA > Profiling /Conditional Text.
2. Select the condition set that you want to use to filer content from the menu.
   
3. Publish the content.

Creating content references

Using a content reference (conref) enables you to pull the content of an element in one topic into the same type of element in another topic.

Examples of things you might use a content reference for include:

• A product name
• A step that occurs in multiple tasks
• A menu option name that might change

<p><ph  id="sugar">sugar</ph></p> 
<p>1 to 2 tablespoons  white <ph conref="myconreff.dita#conc_wj/sugar"/></p> 

Store the shared elements in a separate file. Many topics can point to the shared location and use the content of the element.

If you change the shared information in the source element, any conrefs that point to that element will be updated with the changes.

What can’t be shared as a conref? You can’t include any element that isn’t valid it the current context! For example, you can’t put a <step> element in a concept topic.

Creating the shared content in the source file

1. Create a topic to contain the shared content.
2. Provide a title and short description for the shared content file to indicate that the topic is used to contain shared content.
3. Add the element that you want to share (for example, a paragraph, a note or so on).
   
4. Add an ID attribute to the element.
5. Save your file.

Tip: Keep your shared content in a separate file. Doing so allows you to easily identify what is shared content.

Inserting the content reference in the target file

1. Position your cursor where you want to insert the shared content.
2. Select DITA > Insert Content Reference.
3. In the Insert Content Reference window, click the folder next to URL, navigate to your concept topic, and click OK.
   
4. In the Target ID list, select the element that you want to include.
5. Click OK to insert the shared content.

Developing a reuse strategy

1. Analyze your content.
2. Identify any content that is similar
3. Determine what to do with similar content
   • Can you rewrite the content to make it generic?
   • Can you use conditional processing values to filter the content?
   • Can you rewrite the content to be consistent?
4. Reorganize or rewrite the content
   • Create reusable topics
   • Apply conditional processing values
   • Use DITA maps to organize smaller sets of topics and then reuse that DITA map in multiple deliverables
5. Implement your strategy