[oXygen-user] [oXygen XML Editor Blog] - DITA Linking Strategies
oXygen XML Editor Blog
noreply+feedproxy at google.com
Sat Jul 1 00:08:40 CDT 2017
oXygen XML Editor Blog
///////////////////////////////////////////
DITA Linking Strategies
Posted: 30 Jun 2017 06:11 AM PDT
http://feedproxy.google.com/~r/AboutOxygenXmlEditor/~3/NkzlLkUcD9Q/dita-linking-strategies.html?utm_source=feedburner&utm_medium=email
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: Links are disruptive.
Ideally, users would not need to jump around in content to
read the entire story they are searching
for. Small topics that are
usually read consecutively by the end user can probably get
merged together. 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
PublicationUsing 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: Linking is a form of reuse
so: Reuse small pieces of content instead of
linking to them Avoid too much linking (linking is
disruptive) Use indirect
links. It will allow you to reuse link text and make
profiling/filtering easier while giving you a better overview
of the outbound links for your
project. 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.
--
You are subscribed to email updates from "oXygen XML Editor Blog."
To stop receiving these emails, you may unsubscribe now:
https://feedburner.google.com/fb/a/mailunsubscribe?k=y_tRXtumvTurKTedh51JnlYsGXw
Email delivery powered by Google.
Google Inc., 1600 Amphitheatre Parkway, Mountain View, CA 94043, United
States
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://www.oxygenxml.com/pipermail/oxygen-user/attachments/20170701/2847eb8c/attachment.html>
More information about the oXygen-user
mailing list