5 Tips for keeping your content flexible

Whether you're translating or not, some practices can make it easier for you to future-proof your content. There are five basic tips that localization experts agree on:

Tip #1: Use numbers for your call-outs and have a legend table.

There are two benefits to this "old school" method. If you ever decide to convert your content, there won't be an additional work (or charge) to recreate the call-out content in the new tool. It's rare for two tools to use the same mechanism for drawing features, so it rarely converts cleanly. Second, not all languages fit in the same space, or even go the same direction (right-to-left vs left-to-right). Call-outs will need to be re-sized or moved entirely in a graphic that gets put into a translated document. Both of these mean more work (and more cost) for you at the time the translation happens as well as every time the document is updated. Simply put, use numbers -- not text -- in your call-outs.

Tip #2: Put the call-outs in the graphic itself.

This is a corollary to tip #1. Use the same tool that creates the graphic to insert the call outs so they're part of the graphic and not an in-between layer. Going to a mobile format? Going to the web? Both of these import graphics by reference. If the call-outs are in the graphic, you get them automatically in the other formats.

Tip #3: Don't use variables in text for sentence fragments.

Sentence fragments have ripple effects when it comes to translation. First, not all languages have the same sentence structure. Phrases may not be isolated the same way in another language. Variables should be reserved for items that are not affected by translation like graphics, proper names, numbers, or other truly one-for-one substitutable textual items. Before you use a variable, make sure they pass the isolation litmus test.

Tip #4: Don't nest your topics. (DITA)

Nested topics cause problems for translation houses. Flattened structures can improve the processing because they create a linear-ordering for word experts. This is particularly important when going to Asian languages. Topics need to be fully enumerated before they can be evaluated. Nesting impedes the process and complicates the analysis before translation is completed. With nested topics, the structure is hidden from the translators. It's generally a better practice to use a sub-mapping structure rather than nesting.

Tip #5: Don't use tables for procedures.

First, conversion is complicated for for these kinds of structure. Automated conversion can't tell a procedure from tabular data when a procedure is embedded in a table structure. Second, when you use a table for a procedure, you have to manually maintain the numbering as you insert or delete steps. That's a difficult situation to maintain, especially as the procedure grows and spans pages. Use structures that support numbered steps when that's what you're creating.
Most of the questions had to do with Tip #4 and the notion of what I meant by "flattening" and "nested".

When I talk about "nested" topics, I mean topics that exist completely inside other topics. That is, the entire topic appears between the open and close tags of another topic. A nested topic looks like the structure below:

In this case, there is a complete concept inside another topic. That's a nested topic. And, when I say it's better to flatten, I mean to pull that concept out of the parent topic and make it a topic on it's own. Typically, nesting is used to simulate hierarchical structure. But with DITA, there are other ways to construct hierarchical structure. You can add structure with a map:

The topics in the red box in this map show three levels of hierarchical structure -- what is essentially three levels of heading (head 1, head 2, and head 3) -- without nesting the topics.

And just a note about Tip #2: Remember Tip #1. Or, as one of our customers put it in the Techcomm General TPC Affinity group meeting on the topic...