Strategies for using links with DITA
One of the strategies that always seems to cause me dilemmas with DITA is how to best handle linking.
Mark Baker has an in-depth essay on linking, where he explores many of the issues associated with links. I would point you to the post, but whether to insert the link here or elsewhere is at the heart of many discussions about linking. So I'll briefly delay inserting the link while exploring the risks of doing so.
If I insert the link to Mark's post here, two potential problems occur:
1. You might immediately jump to his post and, because it is rather long, never return here. You'll never get my full argument because I've distracted you with an inline link.
2. The link to his post may return a not-found error. The post is on another site, and I can't ensure that the post will always be available. By linking to it in my post, I create a dependency on the other post being available. (I know this is kind of a stretch here given the web context, but you get the idea in a help material situation. In regular help material, if you link to another topic, it needs to be included in the output for the link to be valid.)
On the other hand, if I wait until the end of the article and insert a relationship table to intelligently surface the link, other potential problems occur:
3. You may never find the link because the web has trained you that links are placed inline where they are relevant, not at a miscellaneous list at the bottom.
4. If the link is inserted at the bottom, you may not know which links refer to which references. I may refer to a dozen ideas in the article -- how are you to know which links correspond to which ideas unless I have a system of endnotes? I can't say, see the post by Mark Baker titled "Re-thinking inline linking: DITA devotees take note!" listed at the end because now I've committed to the article being available, so it's the same as linking inline. If the link is not included, you'll be scratching your head trying to find out where the link is located.
Solutions
I've numbered the problems above so that I can address them individually. Here's how I solve these issues with linking.
1. The idea that inline links distract the reader is hardly plausible given that the billions of pages on the web all pretty much follow this same pattern. As Mark points out, inline links provide a mechanism for wayfinding, helping users who are following the scent of information locate what they're really looking for. Looking for information shouldn't be confused with consuming information.
2. Re creating topic dependencies, a lot of energy seems to be spent on the topic-dependency problem. We don't want to add links to other articles because then you suddenly have all kinds of topic dependencies, and when you single source your 17 different deliverables, it will be a nightmare sorting out which links point to included topics.
Conditionally processing the links can help solve the topic-dependency issue, just as Flare and other help authoring tools solve it. First define your deliverables and the articles intended for each format. Add appropriate attributes to the link statements (such as audience="online"), and then apply the conditional processing when you generate your target. See this post on Hyperwrite, Introduction to DITA Conditional Processing, for more information on conditional processing.
I bet that most online formats will be comprehensive, meaning the online help will contain all the content. For SEO reasons alone, the online format should probably be comprehensive -- see my post Single sourcing and duplicate content for reasons why. It's only the printed deliverables, usually subsets of the online help, where you have to think about topic dependencies.
As an example, let's say you want to print a guide called "Getting Started." In the Getting Started guide, you have a conceptual overview of widgets -- "Widgets overview" -- and a link to an article on "Configuring widgets." You want the link to "Configuring widgets" to appear in the online help but not in the Getting Started printed guide because the "Configuring widgets" topic isn't in the Getting Started guide.
When you link to the topic, you can add an attribute to the paragraph tag to apply conditional processing. To be more specific, you might duplicate the reference statement and tag each statement conditionally, like this:
<p audience="online">For more information, see <xref href="configuring_widgets" format="dita" />. </p>
<p audience="print">For more information, see "Configuring widgets" in the online help.</p>If you're using Oxygen XML, go to Options > Preferences and expand the Editor > Edit Modes > Author > Profiling/Conditional Text option. Edit the audience attribute to include the various audiences you want (online and print).
Then create a new profiling condition set and apply it to your current view.
If you're in the Author mode (rather than Text mode), you can launch the profiling conditions through this toolbar button: 
.
Note that I've actually chosen to refer to the absent topic in the print guide, pointing users to the online help. I could just eliminate the reference altogether, but as a reader, I'd like to know what resources are available, even if the resources aren't included the guide. Readers are smart enough to know that they can simply search for the title in the comprehensive online help to find it. Excluding mention of the topic is problematic because then readers don't know what resources exist.
Also, adding this reference will make your text less awkward. You won't have to wonder if excluding the reference leaves the text feeling like it's missing something by not including a reference to more information about a topic you're only half-way explaining.
A more elegant solution for conditional processing would involve using the key definitions in the map file, changing the link to say "See 'Configuring widgets' in the online help" for the print ditamap. (However, I couldn't quite see how to do this. I don't think it's possible to insert a mere text reference to a missing resource.)
Conditional processing can be problematic if the topic appears in one of the role guides but not the other, and so on. But in these scenarios, it's always going to be a bit complicated.
3. Re the argument that you may never find the link when using relationship tables, this problem is solved if you avoid relationship tables. I just don't think relationship tables are very usable devices for connecting information. They don't apply the links where they need to appear.
4. Re the problem that you may not know which references correspond to which links, again, this is not a problem if you abandon the relationship table idea. Inline linking solves the problem of correlating the right references with the right links.
Oh yeah, here's that article from Mark Baker I mentioned earlier: Re-thinking inline linking: DITA devotees take note.
How do you handle linking with DITA?
About Tom Johnson
I'm an API technical writer based in the Seattle area. On this blog, I write about topics related to technical writing and communication — such as software documentation, API documentation, AI, information architecture, content strategy, writing processes, plain language, tech comm careers, and more. Check out my API documentation course if you're looking for more info about documenting APIs. Or see my posts on AI and AI course section for more on the latest in AI and tech comm.
If you're a technical writer and want to keep on top of the latest trends in the tech comm, be sure to subscribe to email updates below. You can also learn more about me or contact me. Finally, note that the opinions I express on my blog are my own points of view, not that of my employer.