DITA’s New Keys and the 80/20 Rule
Have you ever used the lorem() function in Microsoft Word? How about the rand() function? Do you know all the function keys? Most of us have used Microsoft Word for countless years and don’t know about all of the “hidden” functionality that it offers. Chances are, you’ll know a few of these, but you won’t know all of them simply because you’ve never needed them. Many of these functions are extremely powerful utilities that make Word a versatile application beyond a standard formatted text editor. But they’re available if you ever have the need.
The same is true with some of the new functionality being made available in the forthcoming DITA 1.2 release currently being worked on. Of particular interest is the introduction of keys. Keys provide a way for authors to create addresses to resources through the use of a named identifier rather than to a specific URI pointer. In other words, I can create an easy-to-remember key, like “ms-word-functions” that actually resolves to a URL “http://support.microsoft.com/kb/211982” and link to this URL using the key name in my DITA topic.
Here’s an example of how it works. In my map, I define a topicref and set the keys attribute with an identifier. I also set my href to the physical location of the resource I want to reference.
<map>
<topicref keys="ms-word-functions"
href="http://support.microsoft.com/kb/211982"
scope="external"/>
</map>
In my topic file, I can reference the key that's defined in my map:
<topic id="my.topic">
<title>SampleTopic</title>
<body>
<p>
Lorem ipsum dolor sitamet,
consectetuer adipiscing elit. Maecenas
porttitor conguemassa. Fusce posuere, agna
sed pulvinar ultricies, purus
<xref keyref="ms-word-function">lectus</xref>
malesuada libero, sit amet commodo magna eros
quisurna.
</p>
</body>
</topic>
Now, when the topic is rendered, it will resolve itself to the Microsoft URL defined in my map. Pretty cool stuff. And powerful too. This has many potential uses: localizers can create translated versions of a resource using the same key reference and resolve the link to a locale-specific version of the reference. Consumers can be directed to different resources based on their profile or context within a website.
From an authoring perspective, there's another neat user story: I can reference a "yet-to-be-determined" resource via a key, and when that resource has been created, the key's definition in the map file will resolve the key reference.
Technically, a key definition doesn't need to be reside directly in the map that references that topic. It can live in an "ancestor" map that pulls in the topic indirectly by way of the map referencing that topic. In fact key values can be overridden: Let's assume that I define a key, called "company-website" in Map A that points to "www.company-a.com", and in Map B, I define the same key as"www.company-b.com". Map B also references Topic-1.dita which contains a keyref to "company-website". Map A references Map B. When the Topic-1.dita is rendered in the context of Map B as the primary map, the keyref will resolve to"www.company-b.com"; when Map A is the primary map, the same topic willreference www.company-a.com.
- Map A
Key: company-website = "www.company-a.com"- Map B
Key: company-website = “www.company-b.com”- Topic-1.dita
keyref: company-website
resolves to: www.company-a.com
- Topic-1.dita
- Map B
- Map B
Key: company-website = “www.company-b.com”- Topic-1.dita
keyref: company-website
resolves to: www.company-b.com
- Topic-1.dita
With all great power comes even greater responsibility. Any time a topic makes use of a key reference, that topic is explicitly binding itself to a map(or many maps), meaning that a topic is no longer a unit of information that is completely independent of any particular context in which it is assembled into. You could make the argument that any reference defined in a topic to an external resource (e.g., an image or a cross-reference to another topic) by definition creates a dependency on that topic. And arguably, the referenced (the endpoint) resource is unaware of the object that is referencing it, regardless of whether it's a topic reference or a cross-reference. But there is an additional dependency in the case of keys: Any map that references a topic with a key reference must define the key. So in a sense, not only does the map (or an ancestor map) need to know about the topic, it needs to discover what the topic is about, specifically related to any key references it points to. Consequently, somewhere along the line, at least one map must define the keys used by a topic. Did you get all that? Imagine what your XML authoring tools, CMS systems, and rendering platforms will need to do to manage this.
This is pretty sophisticated and powerful functionality. But the question is, do you need to use keys and keyrefs in order to use DITA? More importantly, will your tools need to support keys to take advantage of DITA's other capabilities? The short answer is no. In fact, I would expect that keys/keyref -enabled DITA support is still a way off for most DITA-enabled tools. Nevertheless, you can still use DITA with the current tools and get most, if not all, of what you need. Just like Microsoft Word with features like MailMerge, keys and keyref will be there if you need them, but chances are, you can get by without them for most content without ever knowing you missed it.
Finally, the possibility of defining indirect links has opens the door to many different possibilities for dynamically driven, profile- and locale-specific content. This is very cool stuff - the kind of thing XML folks like me get excited about. But from a practical standpoint, there are potential downsides too. Keys and key references add another layer of complexity to planning the authoring, deployment and management of DITA content. In reality, most tools aren't ready for this complexity just yet. So while the the standard is ahead of the game, the rest of the industry will be playing catch up. Still, Ride the Wave.
