Content Reuse Strategies for Building Multiple Markets Online Help

The project that I am currently working on is to build help for a web-based application that supports cross-market event registrations.

We write help in DITA. We use DITA OT to publish online help in HTML format, and a tool that I created to delivery embedded XML format help to the application user interface.

To maximum the reuse of content, three levels of strategies are adopted:

• Topic level reuse
• Paragraph level reuse
• Phase level reuse

Topic level reuse

A ditamap can reuse content in the topic level. We have core content for all markets, and market specific content for a specific market. Since maps only processes topics in the same directory as the map, or in the sub-directories of the map's directory. The structure of the content should be maps of each market are stored outside of the core and makets directories. A second level of maps can be created to organize a set of topics for one feature within the core or market directories. This second level maps can be reused by different market maps.

Paragraph level reuse

Conditional text can reuse content in the paragraph level. If there are only one or two sentences difference in a topic for different markets, you can add an attribute to indicate which market this paragraph belongs to. By adding a filter ditaval file to the DITA OT, maket specific paragraph will be delivered to each market.

Phase level reuse

DITA 1.2 keydef element can reuse content in the phase level. The keydef element can be used in combination with the keyword element in a ditamap to define and set "variables" for small pieces of content that may change fairly often, such as UI labels, product name, version etc.

These keys (or variables) can be redefined later in the same map or in another map and all topics that reference the keys will automatically pick up the changes. For example, you can put a particular product name into a DITA map, and indicate in topics where you want the product name to appear. When you generate output using the map, its topics will display the product name in the appropriate places.

Keydef.ditamap

<map>
<keydef keys="marketname">
<topicmeta>
<keywords>
<keyword>Camp</keyword>
</keywords>
</topicmeta>
</keydef>
<keydef keys="eventname">
<topicmeta>
<keywords>
<keyword>Camping sites</keyword>
</keywords>
</topicmeta>
</keydef>
<topicref href="eventsetup.dita"/>
</map>

eventsetup.ditamap
<concept>
<title>Event Setup</title>
<conbody>
<p>You can use ActiveWorks <keyword keyref="marketname"/> to set up
your <keyword keyref="eventname"/>.</p>
</conbody>
</concept>

How to create a DITA OT plugin

When you use DITA OT to publish your DITA content, you might need to customize DITA OT XSL transformation. To make your DITA OT changes portable, you can create a DITA OT plugin.

To create a plugin, you need to first create one or more new or overridden templates xslt files, second create a plugin.xml file to point to your xslt files, and then install this plug-in to your DITA OT.

To create templates

1. Create a folder in dita-ot/demo to store your plug-in, such as my-plugin.
2. Create a folder to store your xslt files in dita-ot/demo/my-plugin, such as xsl.
3. Create a new xslt file to contain the template. It's better that one xslt file only include one function.

To create plugin.xml

1. Copy a plugin.xml file from any existing plugins into dita-ot/demo/my-plugin.
2. If there are more than one <feature> elements, delete the rest and only keep one <feature>.
3. Change the value in the remaining element to point to your new xslt files, separated by commas: &lt; feature extension="dita.xsl.xml" value="xsl/yourxslt1.xsl,xsl.yourxslt2.xsl" type="file" / >

To install your plugin

1. In your dita-ot folder, run startcmd.bat.
2. In the cmd.exe window, type: ant -f integrator.xml.

The plugin that you have created can be easily packed and installed once you upgrade your DITA OT, or pass to others.

How to perform your own transformation using DITA-OT

This task assume that you have DITA-OT appropriate installed in your computer.

DITA-OT transform DITA XML documents to other formats. However, you can tranform any XML document from command line using the Xalan XSLT processor, which is included in the DITA-OT.

To do this:

1. Have your own XSL stylesheet written and make sure it do what you expect with the XML source files they are designed to transform. You can try out using a browser.
2. In the DITA-OT folder, click to run startcmd.bat, which automatically set the system environment variables for you.
3. The command line for most standard transformations is as follows:
   java org.apache.xalan.xslt.Process -in xmlSource -xsl stylesheet -out outputfile

where xmlSource is the XML source file name, stylesheet is the XSL stylesheet file name, and outputfile is the output file name.

If you want the output to be displayed on the screen, simply omit the -out flag and argument

Note:If you are using an external DTD or Schema, you need to have it to be found by the processor. Or you can just delete it from the source file. Otherwise, the processor will complain that it can't find the DTD or Schema.