Excerpts from the targeted review of the linking material

[Kristen James Eberlein <kris@eberleinconsulting.com>]

Below are some of the comments that TC members have made in the linking review. I thought this might be a more useful way for folks to consider some of these comments:

Parent topic: DITA linking

Dick Hamilton
"In general, for this entire topic, I'm having a lot of trouble figuring out what the purpose is, what the prerequisites are, and how this topic fits with the rest of the spec. This is actually a general issue revealed by the targeted reviews. Because those reviews have us looking at topics in isolation, it's possible to see places where information is missing. Conversely, it's hard to tell whether the missing parts are actually missing or are somewhere else in the spec without searching in the spec. I think we need to consider what readers need to know when looking at this (or any) topic, and then provide some guidance for where they can get prerequisite information.

For example, in this introduction to linking, where is the description of the addressing mechanisms? If they're described elsewhere, we need a link, if not, then a description should be part of this topic.

Here are two other general thoughts, which are touched on in my other comments:

1) There are a lot of places where the descriptions are circular. In general, I wouldn't define any concept using DITA elements as a critical part of the definition. For example, defining a content reference relationship as being links "from elements in the topic that specify the conref or conkeyref attribute" requires the reader to look up conref or conkeyref and then try and figure out what aspects of that definition reveal what a content reference is. Since conref has its own complex definition, this isn't easy.

2) I strongly second Kris's thoughts (and the thoughts of others) about terminology. We need to determine which terms are important (do we really need ​ link-defining element​?) and then define them clearly, in non-circular terms."

Stan Doherty
"I feel more frustrated each time I read this section -- now on my third go-round. Within reason, I understanding linking and can certainly use it effectively in many contexts. Describing it and how it should work given this terminology is what is driving me crazy. <content snipped> ... the terms are getting in my way. 

Eliot Kimber
"The "map tree" is the tree of *maps* only, that is, maps and submaps. It is distinct from the topicrefs contained by those maps.

Part of the definitional challenge here is that the map tree is important for the purposes of key space construction: the map tree determines key definition precedence, while the topicref tree reflects the *union* of the topicref trees from all the maps (and the existence of the submaps is not maintained in the final resolved topicref tree)."

Overview of linking

Dick Hamilton

"Do you even need the term link-defining element? How does that term help someone understand links better?

I also agree with Robert that we ought to think twice about creating new terms that are only used in one section and not elsewhere. We should also be careful about creating terms that don't create a meaningful distinction for the reader."

Links within maps

Bob Thomas
"I believe that the term “navigation tree” misses the essence of what we're trying to describe, and that is the native structure of a DITA information network (i.e., the structure that is expressed by a hierarchy of nested, content-referencing, topicref elements). In my mind, navigation is what happens when a structure is traversed. Navigation requires structure, but structure does not require navigation. Terms such as “structural tree” or even "topicref tree" seem more appropriate."

--
Best,
Kris

Kristen James Eberlein
Chair, OASIS DITA Technical Committee
Principal consultant, Eberlein Consulting
www.eberleinconsulting.com
+1 919 682-2290; kriseberlein (skype)