[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: 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 Eliot Kimber 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 --
Best, Kris Kristen James Eberlein Chair, OASIS DITA Technical Committee Principal consultant, Eberlein Consulting www.eberleinconsulting.com +1 919 682-2290; kriseberlein (skype) |
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]