Reuse with Key Scopes

Read time: 2 minute(s)

Using DITA 1.3 key scopes you can reuse a topic in multiple places in the DITA Map with slightly different content.

Reuse using key scopes

Let's say you write a topic about Windows installation for your software product:

<!DOCTYPE topic PUBLIC "-//OASIS//DTD DITA Topic//EN" "topic.dtd">
<topic id="installation">
  <title><ph keyref="osName"/> Installation</title>
  <body>
    <p>
      <ol id="ol_g5h_st4_zt">
        <li>Download the executable.</li>
        <li>Run the executable by double clicking it.</li>
        <li>Follow steps described in the installation wizard.</li>
      </ol>
    </p>
  </body>
</topic>

and at some point your realise that exactly the same steps need to be followed for the Linux installation. The only difference is the name of the operating system. You use a keyref to refer to the operating system name but just with DITA 1.2 support the key will resolve to a single value.

Using keyscopes in the DITA Map you can define multiple values for your key depending on the context:

 <topicgroup keyscope="windows">
  <keydef keys="osName">
   <topicmeta>
    <keywords>
     <keyword>Windows</keyword>
    </keywords>
   </topicmeta>
  </keydef>
  <topicref href="installation.dita"/>
 </topicgroup>
 <topicgroup keyscope="linux">
  <keydef keys="osName">
   <topicmeta>
    <keywords>
     <keyword>Linux</keyword>
    </keywords>
   </topicmeta>
  </keydef>
  <topicref href="installation.dita"/>
 </topicgroup>

You can find a more detailed example and download samples for reuse based on key scopes in this blog post: DITA 1.3 Key Scopes - Next Generation of Reuse.