How DITA Variables Saved my Sanity


If you’ve ever been on a software project where UI changes that affect your documentation are made frequently, you understand how frustrating writing about it can be. With FrameMaker, variables make this a cinch. In DITA, it’s not so straightforward. But the power of content reuse can save your production time — and your sanity.

Enter the humble conref, or content reference. On the surface, a DITA conref is a simple way to reuse content in multiple places so updating is quick and easy. Using conrefs, DITA elements can become variables.

I recently worked on a software documentation project where the need for variables was clear from the beginning. I decided to create a list of reusable UI controls, windows, and screens, so that when the a window or button name inevitably changes, I only have to update it in one place.

Here’s the overall process I used:

  1. Create one topic for reusable elements.
  2. Make a list of all GUI controls.
  3. Give each element a unique ID.
  4. Use a conref to the reusable elements in your content.

Create one topic for reuse.

I made one topic to house all the reusable elements. Hint: name the topic so it sorts to the top of the folder structure so it’s easier to find (an underscore or other symbol should accomplish this).

Make a list of all GUI controls.

In the reuse topic, list the names of all buttons, window titles, tabs, pages, and dialog boxes using the elements wintitle and uicontrol. Wizard and dialog box text fields, drop-down menus, and check boxes are recommended as well, though I didn’t go to this level of detail. This will take some time, but is definitely worth the effort.

To help GUI controls with the same name stay away from each other, divide the list into different sections.

Topic showing reusable elements

Reusable Elements List (oXygen topic)

Give each element a unique word-based ID.

Each element should have a unique ID that is easy to find and remember. I recommend using words instead of numbers for this reason, especially when you have hundreds of elements. Phrases such as “save-dialog” and “save-button” will keep the guesswork to a minimum, especially when GUI controls use the same name.

Insert a conref to the element.

Finally, in your content topic where you want the variable element to be used, reference the element’s ID. oXygen’s wizard (shown below) makes this quite easy.

Inserting a content reference using oXygen

Insert Content Reference (oXygen)

You’re done. Enjoy your sanity!


2 Responses to “How DITA Variables Saved my Sanity”

  1. You’re right: conref is a great way to innoculate yourself against changes in the names of UI elements, names of features, and so forth.

    You might also try using keys and keyrefs: they do much the same thing, and you can use them to build parallel sets of documentation from the same set of source files. In fairness, however, they’re not as simple and straightforward as conref — so your newly-won sanity could be in for a rough ride.

    • 2 Christina Mayr

      Great points, Larry! Keys and keyrefs are something we’re definitely working up to. I’m investigating using keyrefs for links to our other publications. But, as you said, it’s not very straightforward.

Leave a Reply

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

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

Google+ photo

You are commenting using your Google+ 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 )


Connecting to %s

%d bloggers like this: