Put the drawing tools down!

Alan Pringle / Tools5 Comments

This list of technical writing myths has a decidedly DITA slant; I don’t necessarily like the idea of DITA driving what is and isn’t acceptable practice for technical writing. That being said, I endorse the information provided about myth #4:

4. The Callouts on Graphics Myth

If you want to reuse the same graphic in multiple publications and even multiple languages, it is a good practice not to put callouts in the source file of the graphic itself. Instead, you place your callouts “on top of” your graphic in your text editor (Word) or DTP program (InDesign, FrameMaker, …). This is not supported in DITA. Therefore, if you need to use callouts in graphics, try to use language-independent ones (A, B, C…) in the source file of the graphic and put the explanation of these callouts in a table below the graphic in your DITA XML content. [Yves Barbion]

It’s not just the DITA standard that doesn’t support callouts placed with a document processor’s drawing tools. We have a client for whom we created a custom XML structure for FrameMaker content, and that content contains many graphics with callouts. The client translates the content into multiple languages.

In the previous workflow in unstructured FrameMaker, the client placed the callouts in the anchored frame with FrameMaker’s drawing tools. However, if you do that in a structured FrameMaker workflow and save content out to XML, FrameMaker by default saves each image with added callouts into a new CGM graphic file that no longer has editable callouts. There can’t be complete round-tripping between XML and FrameMaker because the graphics aren’t preserved in this scenario.

Therefore, the rule for this client is that an anchored frame can contain just one image file imported by reference. Period. No other text, text frames, or anything. If callouts are necessary, they are included as part of the source graphic; the client adds numbered callouts in Illustrator. A numbered list specifically for explaining those callouts follows the graphic.

The XML generated from FrameMaker points to the image files, and FrameMaker doesn’t need to generate new graphic files to include any callouts added with FrameMaker’s drawing tools. (If the directory containing XML files includes a CGM file that FrameMaker created during export, that usually means there is an anchored frame somewhere that contains something more than just a referenced image file.) Another huge plus: because the callout explanations are part of the text, they are translated without changing the original graphic.

Separating callouts from your images and making them part of the text is smart for any workflow because of localization issues, and it pretty much becomes mandatory when you’re establishing an efficient structured authoring environment (and not just those based on DITA).

P.S. One other thing to think about with graphics in structured authoring environments: if you use XSL to transform your XML into online formats, determine if web-ready graphics (such as PNG files) will work in your print/PDF and online content. If so, you eliminate the need to convert images to formats for online viewing.

About the Author

Alan Pringle


Content strategy consulting. Publishing (electronic and print). Eating (preferably pastries and chocolate). COO at Scriptorium.

5 Comments on “Put the drawing tools down!”

  1. When I first jumped the fence from managing Tech Doc teams to working for software vendors it was in the grapics arena and this was a topic we spent a lot of time discussing with clients.
    And it’s a question I still get asked today when I do my “use more graphics” rant.
    The two Best Practices I can recommend are:
    1. If you want to use callouts that will be translated, instead of using text on the source graphic use a generic key. Use a pointer or leader line and label it with a simple number (1) or letter (A), then have a table in the text stream under the graphic that relates the label to the item. That way if it needs to be translated it can be handled the same way you do for another text and the source graphic never needs to be changed.
    (2) If you MUST add callout text to the graphic, then use an illustration tool / standard (like CGM / SVG etc.) that supports layers and keep the text on a separate layer. Yes you still have to translate that layer, but when you change the graphic you don’t have to recreate the whole thing, just one small part of it.

  2. OK, there are limitations what tools currently support. And it is not a bad idea to tell clients about it and to show them some work-arounds.
    But: Speaking of FrameMaker, there is no *technical* reason, why the content of anchored frames should not be roundtripped to XML and back to FrameMaker. The technology is available, and I know of companies that built there own XML import/export client that keeps all anchored frame content without a problem.
    There are situations where direct callouts are useful for the target audience and we should communicate that to tool manufacturers. Including this information into processes will then be our next task in consulting.

      1. Interesting to see how DITA-FMx handles those callouts.

        If you did keep the callouts in the figure and preserved them with DITA-FMx, you’d need to carefully consider the expansion of translated text. Your source graphic should have plenty of room to accommodate longer text strings. In that regard, I think using numbered callouts and legend is probably a safer bet.

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.