One of the articles in our newsletter this month generated a great discussion with one of our customers. I wanted to follow up here with their questions and some deeper information.
First: here’s the article from the newsletter:
Whether you’re translating or not, some practices can make it easier for you to future-proof your content.
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 reader put it:
“If there is any chance that your docs will be translated, do not embed text (words) in the graphics. It will cost you $25 to $50 per graphic, per language, to have the LSP (localization service provider) open each graphic, translate the text, save the graphic, and replace the file in your authoring tool or CMS.
Cost saver tip: Before translating your docs, replace all text in graphics with numbers and use a legend table below the graphic as described in Tip #1.
Usability tip: if possible, keep the legend table on the same page as the graphic.”
Get useful tips and valuable resources every month
Join the thousands who know just how much we share.