This small tutorial is based on the "DITA Linking Strategies" presentations I made for
the DITA Europe 2016 and DITA North America 2017 conferences. It's a general overview about
DITA linking possibilities and best practices. Also, it's meant as a continuation of the DITA Reuse Strategies blog post.
According to Wikipedia:
"A link, is a reference to data that the
reader can directly follow either by clicking, tapping, or hovering."
Basically, we should regard linking as yet another form of content reuse, except that
instead of presenting the content in place, it re-directs the end user to some other
resource.
I'll start with describing linking at DITA Map level.
Map-Level Linking
A DITA Map uses topic references to assemble the content of a
publication.
<topicref href="installation.dita">
<topicref href="server_installation.dita"/>
<topicref href="client_side_installation.dita"/>
</topicref>
Depending on the output format, the topic reference may be a link in the table of
contents for the XHTML-based outputs or it may be interpreted as a content reference for the
PDF-based output that generates a single monolith document. So the role of the
topicref is dual, it may sometimes be regarded as a link to a topic and
sometimes as a content reference.
Chunking
DITA topic modules should be kept as small as possible, but sometimes the end user
may need to read more than one topic to achieve a single task. So, when publishing to
HTML-based outputs, you will end up asking yourself this question:
Should I prefer larger
HTML files or more links in the TOC?
And you should always consider these two ideas:
For example, if the installation of your product requires installing both a
server-side and a client-side component, by using DITA chunking you can choose to have
separate DITA topic modules for each of the installation procedures but merge the topics
together in the web-based
outputs:
<map>
<title>User Guide</title>
<topicref href="installation.dita" chunk="to-content">
<topicref href="server_installation.dita" toc="no"/>
<topicref href="client_side_installation.dita" toc="no"/>
</topicref>
</map>
You can read more about chunking in the DITA 1.3 specification. The DITA Style Guide also has a good overview about why
it is preferable to write small topics and then merge them together using the chunking
mechanism.
Topic-Level Linking
Links that appear inside topics can be divided into various categories and I'll
discuss each of these categories separately.
In-Content Links
In-content links are links added manually in the topic
content:
<li>See: <xref href="http://www.../" format="html" scope="external"/></li>
You should keep in mind that this kind of link is disruptive to the reading
experience because when end users encounter them, they need to decide weather to read
further on or to follow the link. On the other hand, this may sometimes be a good thing. For
example, one of the installation steps may require the end user to download a certain
library from an external website before continuing.
You can read more about links in general in the DITA 1.3 specification. The DITA Style Guide, written by Tony Self, also
discourages the use of in-content links.
Related Links
Related links are placed at the end of the DITA topic and they allow the end user to
explore additional resources after the current topic has been
read.
<related-links>
<link href="http://tomcat.apache.org/" format="html" scope="external"/>
</related-links>
To minimize disruption when reading the content in general, the preferred place where
to place links is at the end of the generated HTML page.
You can read more about related links in the DITA 1.3 specification.
Defining Related Links using Relationship Tables
Related links do not need to be manually added at the end of each topic. You can
define relationship tables in the DITA
Map:
<reltable>
<relrow>
<relcell>
<topicref href="client_side_installation.dita"/>
</relcell>
<relcell>
<topicref href="server_installation.dita"/>
</relcell>
</relrow>
……..
</reltable>
These tables can define associations between two or more topics, associations that
automatically contribute to the related links creation in the generated HTML output.
Here are some benefits of using relationship tables:
-
A topic should have as few links as possible defined directly within. This makes it
easier to reuse the topic in various contexts and keeps it as separate as possible for
other parts of the DITA project, decreasing the possibility of broken links.
-
By default, links defined in relationship tables are bi-directional, allowing users
to land on any of the topics when searching for solutions and find their way to the
related ones.
-
Using a relationship table separates the task of writing topics from the task of
finding relationships between topics.
You can read more about relationship tables in the DITA 1.3 specification. The DITA Style Guide also recommends using relationship
tables.
Indirect Links (Key References)
All the link samples we've look at so far have been direct links, links that point to
the target using the
@href attribute. Indirect links require two steps:
- Define a key in the DITA Map for the
target.
<keydef keys="client_installation" href="client_side_installation.dita"/>
- Use the defined key to reference the target
resources.
<xref keyref="client_installation"/>
Here are some of the benefits of indirect linking:
-
Offers the ability to reuse link target text and meta data. If you want
to have custom text for a certain link, you can define it directly in the DITA
Map:
<keydef keys="dita_ot_website" href="http://www.dita-ot.org/" format="html"
scope="external">
<topicmeta>
<linktext>DITA Open Toolkit Web Site</linktext>
</topicmeta>
</keydef>
and
then add key references in all other
places:
<xref keyref="dita_ot_website"/>
-
Easier conditional linking (including links to topics that sometimes may
be missing). If you want your topic to link either to one target or to another
depending on the filtering/profiling conditions, instead of adding profiling directly
on the link, you can add the profiling conditions directly in the DITA
Map:
<topicref keys="slicing" href="slicing_vegetables_for_experts.dita" audience="expert"/>
<topicref keys="slicing" href="slicing_vegetables_for_novices.dita" audience="novice"/>
<keydef keys="slicing" audience="noLink"><topicmeta><keywords>
<keyword>Slicing</keyword></keywords></topicmeta>
</keydef>
and
then link to the key from each topic:
<xref keyref="slicing"/>
-
Easier link management. A good overview about all the outbound links in
your project helps you maintain and control lists of allowed external web sites. With
indirect references, you can define all references to external resources in a separate
DITA Map. An example of a DITA project using indirect links to achieve separation of
links by purpose can be found here: https://github.com/oxygenxml/dita-project-best-practices.
- Makes it easier to move/rename topics. When you move or rename a topic
referenced via indirect links, only the link defined in the DITA Map will break, making
it easier to fix broken links.
There is an overview about indirect addressing on the DITA XML Org website. The DITA 1.3 specification also has a chapter
about indirect links.
Auto-Generated Links
Until now, I've talked about manually added links, either in the topic or in
relationship tables. Using the DITA
@collection-type attribute, you can
define relationships between parent and child topic references in the DITA Map,
relationships that result in automatic links added between
them:
<topicref href="installation.dita" collection-type="sequence">
<topicref href="server_installation.dita"/>
<topicref href="client_side_installation.dita"/>
</topicref>
There are 3 useful types of
@collection-type values:
-
Unordered - Links are generated from parent to children, and from children to
parent.
-
Family - Links are generated from parent to children, from children to parent,
and from sibling to sibling.
-
Sequence - Links are generated from parent to children, from children to
parent, and from child to previous sibling (if applicable) and next sibling (if
applicable).
You can read more about auto-generated links in the DITA Style Guide.
Conditional Links in Distinct Publications
You may publish documentation for multiple products from the same DITA
content. Also, you may want to have links point to various targets depending on the product
for which you want to publish the documentation. Or, you may want to suppress links
completely in certain publications.
When using direct linking, you will need to profile each link depending on the
publication:
Find our more about slicing vegetables: <xref href="slicing_vegetables_for_experts.dita" audience="expert"/>
<xref href="slicing_vegetables_for_novices.dita" audience="novice"/>.
With
indirect links, you can define the profiling attributes as DITA Map
level:
<topicref keys="slicing" href="slicing_vegetables_for_experts.dita" audience="expert"/>
<topicref keys="slicing" href="slicing_vegetables_for_novices.dita" audience="novice"/>
and
thus, simplify the reference made in the topic
content:
Find our more about slicing vegetables: <xref keyref="slicing/>.
Conditional Links in the Same Publication
Using DITA 1.3 key scopes, you can reuse a topic multiple times in a
DITA Map and have each referenced topic contain links to various target topics. For example,
if my
preparing_vegetables.dita topic has a
link:
<link keyref="slicing"/>
you
can define various key scopes in the DITA Map that bind the "slicing" key to various
targets:
<topichead navtitle="Cooking for Experts" keyscope="expert">
<topicref href="preparing_vegetables.dita" keys="preparing"/>
<topicref href="slicing_vegetables_for_experts.dita" keys="slicing"/>
</topichead>
<topichead navtitle="Cooking for Novices" keyscope="novice">
<topicref href="preparing_vegetables.dita" keys="preparing"/>
<topicref href="slicing_vegetables_for_novices.dita" keys="slicing"/>
</topichead>
This
previous blog post contains more details about key
scopes.
Link Text
When linking to an external resource or to a DITA topic or element, the publishing
engine will attempt to deduce the link text from the target context. For example, the link
to a DITA topic or element that contains a <title> will use that
title as the link text. The link to an external resource (for example to
http://www.oxygenxml.com) will, by default, use the HTTP location as the
link text. You can also customize each link text individually. So, ask yourself this
question:
Should I leave the link text to be automatically computed or should I set a more
friendly text?
For internal links to elements that have a title, in general it is more flexible to
not set a custom text and let the publishing engine decide one for you. For external links,
you should usually specify your custom link text.
Should I Link or Should I Reuse?
Suppose you want to bring a certain paragraph, note, or section to the end user's
attention. If that particular target element is not very large, you should always reuse it
(using a content reference) instead of linking to it.
Conclusions
As with all large projects, managing links in a growing
DITA project can be
problematic, so you need to become organized. As an overview of what we've discussed so far,
I suggest the following best practices:
If you want to experiment with the various linking strategies I discussed above, you can
find some samples here: https://www.oxygenxml.com/forum/files/linking-strategies-samples.zip.
