Excerpts from the targeted review of the linking material

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)