DITA's New Keys and the 80/20 Rule

Sun, 10 May 2009 23:39:00 GMT

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 thanto 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.

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 orcontext 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

Map B
Key: company-website = “www.company-b.com”

Topic-1.dita
keyref: company-website
resolves to: www.company-b.com

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 possiblity 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.

Content Management Strategies/DITA North America Conference Review

Fri, 08 May 2009 20:26:00 GMT

I wasn’t able to attend many of the session since I was manning the Flatirons Solution booth. Yet from talking with the attendees who visited with us, here are some of the key takeaways:

DITA is here to stay. This is not news, but the key point here is that organizations are adopting the standard in earnest, as evidenced by the 150-200 attendees who came despite a bad economy, and discretionary budgets being whittled to next to nothing. This means that organizations are thinking about DITA as an integral part of their long term strategy.
DITA’s scope is not only Technical Publications. Again, not earth-shattering news. With specializations like Machine Industry, Learning Objects, and gobs of others, DITA is extending its reach to whole industries that haven’t been able to take advantage of XML before now. At the conference, I spoke to attendees in a wide range of industries including bio-tech, and manufacturing.
Shifting focus from Content Authoring to Content Management and Content Delivery Services. This is a fundamental shift. Eric Severson emphasized this point when he demonstrated that Microsoft Word could be used to create DITA for a specific class of users that aren’t the primary audience for more conventional XML authoring solutions. Obviously this raised a few eyebrows in the audience, but the point is that DITA’s architecture is such that even casual contributors, given a few minor constraints in Word, can certainly provide content that can be easily turned into DITA.
DITA will live in Middleware. This is a key point. While the focus of the conference was centered around DITA and content management, there’s more here than meets the eye. I had the opportunity to sit in on the open forum that discussed upcoming v1.2 features. Many of these features are centered around link handling (things like keyref, conref push, and conref keys [conkeyref]). There will be greater emphasis on managing all kinds of linking, including indirect links that could have significant implications on vendors’ existing architectures. While it still will be possible to manage small projects from simple file management strategies (including things like Subversion), larger projects and enterprise-wide implementations, particularly those that want to take advantage of these new features will need more sophisticated applications (read: a content management system) to manage the myriad of link strategies being made available.

Even rendering tools will need to be more sophisticated to support these new features. The DITA Open Toolkit is currently working on a new version (1.5) to support these. Other rendering applications will need to start thinking about how they plan to support these features.

I’ll have more thoughts on this particular topic later. Suffice it to say that there are some key assumptions that current DITA adopters take for granted and make impact how they design and create content in the future.
XML Authoring tools will get more complex. To support all the new features coming in DITA 1.2, DITA-aware XML authoring tools will need to be tightly integrated into middleware systems, particularly the CMS. There will also be a strong emphasis for authoring tools to handle a wide variety of link and referencing strategies. I anticipate that these applications will be more process-intensive, with larger footprints on a user’s PC. I also anticipate that the level of sophistication required to “operate” these tools will be much higher. So the emphasis for XML Authoring tool vendors will have to focus on both features and usability.

This conference was illuminating on many different facets. Even the vendors I spoke to seemed to realize that DITA is a truly disruptive technology that has changed the way the entire industry thinks about XML. In the current economic reality, this is the perfect time to be thinking about what this all means and how organizations can take advantage of these innovations in their environment. Ride the wave.

Jim Earley

DITA's New Keys and the 80/20 Rule

Content Management Strategies/DITA North America Conference Review