Re: Key-based (indirect) cross-reference best practices


Chris Papademetrious
 

Thanks Radu, this is fantastic real-world information!

> From what I remember Eliot Kimber advises that you should have key for each topic

This is indeed the recommendation I referenced, on slides 15 and 16 at


In FrameMaker-to-DITA conversion, I can implement any reference approach; it's just code. The more important consideration is how easily my writers can work with those references and maintain the approach when creating new content.

My interest in indirect references came from researching cross-deliverable links in DITA. Our FrameMaker books have cross-book links, implemented via markers and some post-processing. I need to convert and store these cross-book references in the proper DITA format, then implement similar post-processing in our PDF and HTML5 DITA-publishing flows.

> For example in the Oxygen User's Manual we use conkeyrefs to refer to
> reusable content but all other links are based on direct references.

I thought about implementing something similar -- using file-based links by default, then converting the targets of any cross-book links to @keyrefs. This adds complexity to conversion, but it's implementable.

But how do writers maintain this mixed approach? If book A's writer creates a link to a destination topic in book B that has no key, then that topic's <topicref> must be converted to a key-based reference first. Now book A's owner must ask book B's owner to do the modification, which adds time and effort to what should be a simple cross-reference creation.

> I would probably define a key for a topicref either if it's referenced in
> multiple places in the DITA Map, or if it's referenced from other topics
> either as link or as conref

Does this mean you would use keys for topics referenced from other topics *within* the same book? I suppose this makes sense, as then you'd no longer need to modify all those references if the source location changes. (This could also reduce the footprint for revision control.)

You describe some actions in Oxygen that I will need to go investigate - thank you!

Thinking out loud -- it might be nice to have Oxygen automatically convert a file-based @topicref to a key-based @topicref whenever a reference is made from outside that topic to something inside the topic. Oxygen could prompt for a @topicref key value to use, with the dialog box pre-populated from (or providing a choice of) the topic ID, topic file name, or a simplification of the topic title, etc. If this approach is agreed upon across the team, then (1) no writers need worry about the how/when/what details of key creation, and (2) there should be no resistance to writer A converting a destination topic in book B from file to key. Existing file-based references would continue to work, although some scriptware could easily detect and implement them as key-based (or this could be an Oxygen feature too).

This is basically an automated version of your comment here:

> Tech writers need to perform that extra step of defining the key after
> the topic reference is added.

designed to address this aspect:

> Indeed working with keys adds an extra layer of complexity due to the
> indirection. And if you consider the tech writers may choose to reject
> the entire solution because of this...

There is another aspect I must consider. We have a specialization of <topic> called <module>, which we use for minor subtopics (always nested within a parent topic in a file) that should be omitted from navigable topic lists. <module> must be specialized from <topic> and not <section> because they can have their own related links in the FrameMaker source, which gets converted to something like this, which <section> cannot represent:

<topic>
  <title>Fruit</title>
  <body>...</body>
  <module>
    <title>Apples</title>
    <body>one or two sentences</body>
    <related-links>...</related-links>
  </module>

  <module>
    <title>Oranges</title>
    <body>one or two sentences</body>
    <related-links>...</related-links>
  </module>

</topic>


To prevent a <module> from being shown as navigable, we omit its <topicref> and its content is implicitly included with its parent's content:

<topicref href="vegetables.html"/>
<topicref href="fruit.html"/>
<topicref href="dairy.html"/>

But now there is no <topicref> to define a key for the <module>s, which prevents me from using key-based references to or within them. I guess I would need to explore how a module <topicref> could be present but omitted from PDF or HTML5 navigation.

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