Key-based (indirect) cross-reference best practices


Chris Papademetrious
 

Hi all,

I saw a best-practice that said cross-references should be key-based and not file-based, and I'd like to start some practical discussion about it.

Let's start with something simple.  :)  I'm converting about 100 books from structured FrameMaker to DITA. Currently, all my DITA <xref> elements use file-based references. I adjusted conversion to

  • Assign a unique @keys value to every <topicref> in the bookmap
  • Adjust all cross-topic <xref> elements to use key-based references

But now our larger books have over a thousand key values, which makes the key list in Oxygen's cross-reference dialog box a bit daunting!

Some topic files contain their tightly-associated subtopics in the same file. Currently I define keys for these nested subtopics:

<topicref   href="fruit.dita"          keys="fruit">
  <topicref href="fruit.dita#BABFAFBE" keys="apples"/>
  <topicref href="fruit.dita#BABCDIBF" keys="oranges"/>
  <topicref href="fruit.dita#BABICJEB" keys="pears"/>
</topicref>

From a best-practice perspective, should I generate keys only for the top-level topics of such files, given that their tightly-associated subtopics will likely stay in place?

<topicref   href="fruit.dita"          keys="fruit">
  <topicref href="fruit.dita#BABFAFBE"/>
  <topicref href="fruit.dita#BABCDIBF"/>
  <topicref href="fruit.dita#BABICJEB"/>
</topicref>

I have more questions, but I think it's best to walk through the topic (sorry!!) incrementally.


 - Chris



Join main@dita-users.groups.io to automatically receive all group messages.