Dissecting DITA relationship tables

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?”

IBM Selectric Typewriter (1961)

IBM Selectric Typewriter (1961)

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.

Topic-based authoring (XML.com)

Topic-based authoring (XML.com)

For a product-based perspective, take a look at these quick but concise videos:

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.

Standard three-column reltable (Madcap Flare)

Standard three-column reltable (Madcap Flare)

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.

Standard three-column reltable (PTC Arbortext Editor)

Standard three-column reltable (PTC Arbortext Editor)

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.

Unidirectional two-column reltable (PTC Arbortext Editor)

Unidirectional two-column reltable (PTC Arbortext Editor)

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.

Bidirectional two-column reltable (PTC Arbortext Editor)

Bidirectional two-column reltable (PTC Arbortext Editor)

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!

Oxygen XML Author: Topic XML view in green

Oxygen XML Author

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s