An appeal for DITA keys: Powerful, useful, and mostly ignored

Last week, in his webinar on conditional content, Noz Urbina showed a demo of content reuse using DITA’s conref attribute. I took the opportunity to ask for Noz’s opinion of keys and keyref.

Keys provide a powerful and useful function, Noz replied. But few people use them because the authoring tools don’t do a very good job of making them easy to use. And the tool manufacturers haven’t added the functionality because they don’t think anybody wants to use it.

It’s the classic chicken and egg scenario.

Noz is one of the smartest people in the content publishing space (and I highly recommend viewing that webinar, if a recording becomes available.) But is the story of keys really as simple as he makes it out to be?

Are people champing at the bit to use keys, but finding themselves stymied by the tools? I’m not sure that’s the case. Noz is right that most tools don’t support keys particularly well. But I think there’s another problem as well: five years after keys were introduced, a lot of people still don’t understand the use cases and the basic mechanisms behind keys. I can’t prove this, but I think that most people who learn DITA don’t learn to use keys at all.

My own experience bears that out. When I learned DITA I had no trouble grasping conref, filtering, and topic-level reuse. But for a long time keys had me flabbergasted. Why would I ever use them in lieu of conref? Exactly what machinations would I have to perform?

I don’t think I was alone. Not long after keys were introduced, Eliot Kimber posted a detailed example of its use in the DITA Users group on Yahoo. He did so, he said, “because keyref is so important and because it also has inherent, unavoidable complexity.”

There you go. If Eliot Kimber thinks it’s complex, then it’s really complex. Yet Noz is right, too, when he says that keys are powerful and useful.

So what can be done to bring this feature into general use?

First, make it simpler. Noz hinted that that might happen in the upcoming DITA 1.3 implementation, and I hope he’s right.

Second, publish information about it, for use when training authors (or at least architects) in DITA. The information should describe not just how to use keys, but why — by which I mean use cases. Here’s a good one that I found, courtesy of Sarah O’Keefe. We need more like it.

Have you tried to use keys? If so, I’d like to hear about your experience with them. Or were you scared off? I’d like to hear about that too.