Author Max: Great DITA, Great Documentation


The DITA Project #16: Why Use Keyrefs?

Posted in DITA, Minimalism, Technical Documentation by katriel on the August 28th, 2012
yKeys make extentsive content reuse easier to maintain and enables  sophisticated conditional processing (profiling) of content.
Without using keys, extensive use of related links, cross references and conrefsthese features results in a loss of portability; meaning, it makes it difficult to move, rename, break up or combine topics. When a topic is moved, every reference to the topic will need to be updated to reflect the new location of the content.
To enable reuse and portability, use the “keyref” feature. Keyref provides an indirect addressing mechanism. You can use either topicref elements or keydef elements  to define keys in a DITA map. Topics can be given a symbolic name (keys attribute) that points to a topic file path (href attribute). Future references to such topics are made using a key reference (keyrefattribute). At a later point in time, if the topic is relocated, the path needs to be updated only in the map where it is defined. All other references will automatically pick up the new location.
The “keyref” feature also enables sophisticated conditional processing (profiling) of content. Without keys, attribute-based conditional processing (such as product,platform, and audience) is a powerful feature that enables content reuse, but in a large set of a documents, content can become difficult to maintain due to the number of variables. Keyrefs simplify authoring and production of conditional content.

Keys make extentsive content reuse easier to maintain and enable  sophisticated conditional processing (profiling) of content.

Without using keys, extensive use of related links, cross references and conrefsthese features results in a loss of portability; meaning, it makes it difficult to move, rename, break up or combine topics. When a topic is moved, every reference to the topic will need to be updated to reflect the new location of the content.

To enable reuse and portability, use the “keyref” feature. Keyref provides an indirect addressing mechanism. You can use either topicref elements or keydef elements  to define keys in a DITA map. Topics can be given a symbolic name (keys attribute) that points to a topic file path (href attribute). Future references to such topics are made using a key reference (keyrefattribute). At a later point in time, if the topic is relocated, the path needs to be updated only in the map where it is defined. All other references will automatically pick up the new location.

The “keyref” feature also enables sophisticated conditional processing (profiling) of content. Without keys, attribute-based conditional processing (such as product,platform, and audience) is a powerful feature that enables content reuse, but in a large set of a documents, content can become difficult to maintain due to the number of variables. Keyrefs simplify authoring and production of conditional content.

In future posts, more of the nitty gritty on using keyrefs.

Leave a Reply