Playing Devil's Advocate with Keys

["David J. B. Hollis" <dhollis@aandoconsultancy.ltd.uk>]

Hi Kris, et. al.

I'm aware that there's a key review in progress, and this post will hopefully support that. I do appreciate, however, that this is somewhat left-field.

At a certain recent contract, I worked with a number of very intelligent authors, many of whom were from an electronic engineering background. Some were quite capable of creating conversion scripts that took machine readable content, and turned it into DITA.

Now, two of these guys, totally independently, came to the same conclusion about keys. And that was that it had to be the keyword element that is the means of adding key content to a topic.

Now, OK, to the 'DITA-rati', that is completely bonkers. But, thinking about it, it does make some sense.

But, I'll pause and explain that they both had the same blind spot when it came to DITA. They simply didn't want to read the DITA Spec., nor the very useful Adoption TC article about keys. As far as they were concerned, that was not their job, it should be someone else who reads this stuff, and then spoon feeds them what they need to do. OK, to some extent I understand that, except that they were part of the guinea pig team and project, and so really had no excuses. I actually had to badger one of them for some time before they would read the article!

So, if someone comes to DITA with little or no reading, training or understanding, how might they approach keys?

Well, they start with the keydef element. That is part of the map, and it points to a topic. OK - fine. Create a topic with the referable content.

OK, so topic with content, and keydef in a map. What's next?

Well, keydef is an element, so what is the corresponding element that puts the keydef content into a topic. Ahh, keyword! Obviously!

So, that's what they did, or tried to do. And, of course, it didn't work.

For the TC, is there anything that needs to be done, and possibly incorporated into the Spec.?

Some thoughts:

1. Somehow make it abundantly clear that DITA allows referable content from any element in one topic to the same element in another topic. There is no 'special' element. All elements are equal, and can access the same keys mechanism.

2. Because referenced content works for any element, the keys mechanism is primarily attribute, not element based. The only exception being the keydef element.

3. A note as part of the keyword element description, that it is NOT part of the keys mechanism. It is merely an unfortunate coincidence that it happens to have 'key' in its name.

OK, I suppose some might say that no amount of additional notes or cautions are going to stop someone doing as described, if they are not prepared to read the DITA Spec. in the first place!

That's certainly true, but it might be useful for someone?

I hope this helps?

Many thanks,
David