Hi, my name is Jay, and I’m an IBM TRIRIGA information developer at IBM. This time, to give you a quick taste of the work that I enjoy, I’m going to talk about DITA relationship tables, just one of the many elements of writing, authoring, or developing in DITA-XML.
First of all, what is an information developer?
I wondered the same thing when IBM first announced its intention to acquire TRIRIGA. In other words, the real question is “What is the difference between an IBM information developer and a technical writer?”
Haha, no, this isn’t the start of a bad IBM joke. But honestly, I think the essential difference is that IBM technical writers primarily develop content in topic-based DITA-XML source files, not in Microsoft Word, Adobe FrameMaker, or other less-modular source files. So I presume that technical writers who develop in DITA-XML at other companies or organizations are also viewed as information developers.
What is DITA-XML?
If you’re not familiar with DITA-XML topic files or topic-based authoring, then try to think of individual topic files like individual scenes in a movie screenplay. Like movie scenes, topic files are the basic building blocks that can be individually added, edited, deleted, or rearranged to create a different or more-effective experience.
For a product-based perspective, take a look at these quick but concise videos:
- Madcap Flare 9: An Overview (YouTube: 3 minutes)
- Adobe FrameMaker 11: Creating a DITA topic (YouTube: 6 minutes)
- PTC Arbortext Editor 5.4: Highlights (YouTube: 2 minutes)
Unfortunately, IBM doesn’t provide Madcap Flare or Adobe FrameMaker. Instead, while it might not have the prettiest interface, PTC Arbortext Editor still gets the job done and is still the DITA-XML authoring tool of choice at IBM. Although Oxygen XML Author is scheduled to replace our PTC Arbortext Editor in the near future, I haven’t seen any specific dates yet.
What is a DITA relationship table?
Unlike typical data tables that are displayed in the page or topic, relationship tables or reltables aren’t meant to be displayed in the output at all. Instead, a reltable is intended to centralize and organize all of the interrelated links that you define between any two individual DITA-XML topics in the chapter, branch, or entire tree structure of the documentation.
Which type of DITA reltable should I use?
This question is typically asked by newer information developers. When I first started to learn about DITA authoring, I wondered the same thing. In other words, the real question is “Should I use the three-column or two-column reltable?”
You might say, “Hey, wait a minute. I’ve never seen a two-column reltable before.” But guess what? I use them all of the time! I’ve created both unidirectional and bidirectional two-column reltables. In fact, you can probably create reltables with any number of columns. That is, until you realize how cluttered it can get when you insert long topic references into skinnier and skinnier columns.
First, the standard three-column reltable contains a column for each of the three basic topic types: concept, task, and reference. Any topic in any column can be defined as a source-only or target-only topic. Like in all reltables, the related links are generated for each row in the reltable.
Next, the unidirectional two-column reltable defines a column for the source-only topics and a column for the target-only topics. I always pair this reltable with the bidirectional reltable below. Concept, task, and reference topics aren’t restricted to a specific column.
Last, the bidirectional two-column reltable defines two normal columns. I always pair this reltable with the unidirectional reltable above. Again, concept, task, and reference topics aren’t restricted to a specific column.
So which reltable should you use? The answer is “It depends. Whichever works best for you or your team.” Naturally, there are advantages and disadvantages to each reltable style, but both the three-column and two-column types achieve the same goal of linking the related DITA-XML topics. In the end, since reltables aren’t displayed in the output, it comes down to your personal or team preference. Personally, I like the pair of two-column reltables, because instead of thinking in terms of concept, task, and reference topics, I’m thinking more easily in terms of one-way and two-way links.
Do I have an update?
Three weeks later, I found myself breathing Oxygen XML!
- Tech writers: The bard class of the corporate world (customersandcontent.com)
- The Hitchhiker’s Guide and today’s technical documentation (larrykunz.wordpress.com)
- Part (8) Reasons to upgrade from FM 7.x to FM 11: “Real” support for DITA (blogs.adobe.com)