RE: Translating documentation/insertion of screen shots

Subject: RE: Translating documentation/insertion of screen shots
From: "Glenn Maxey" <glenn -dot- maxey -at- voyanttech -dot- com>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Thu, 3 May 2001 15:37:15 -0600

I've been-there-done-that. Here's some unsolicited advice up front. Even if
it means delaying the translators efforts and ultimately the first release
by two weeks to a month (or longer), GET YOUR DOCUMENTATION HOUSE IN ORDER

By this, I mean that you need to take the time to clean up directories from
unused files. Get rid of and resolve duplications. Have someone do this for
all images. Go through your documents and assure rigid adherence to a
template for formats and styles. MOVE ALL LANGUAGE INDEPENDENT graphics to
their own directory even if it means breaking links and having to re-create
them. Make sure that all images are referenced and not embedded.

Also, INSTEAD OF implementing a directory structure like:

Project QQQ
+ manual1
++ English
++ Spanish
+ manualn
++ English
++ Spanish

Do your language split at the top level:

+ Project QQQ
++ manual1
++ manualn
+ Project ZZZ
++ manual1
++ manualn
+ Project QQQ
++ manual1
++ manualn
+ Project ZZZ

This way, you can copy all of the files from your source language all in one
go. When you get your targets back, they're all together. This may seem
obvious, but I had to fix an organization that was worse than this; not only
was the language split at the bottom level, but the documentation for
project QQQ was buried in the source code. GROUPING ALL DOCUMENTATION
TOGETHER (separate from other "garbage") by language is important and is the
only way (IMHO) to keep an overview.

If you don't take a step back NOW, it will come back to haunt you again and
again. For each language. For each release.

When getting your house in order, you might want to consider implementing a
naming scheme for your images. Obviously, descriptive names are important.
Just as important are names that naturally group images together and provide
a sequence.

For example, if the user is taken through a series of dialog boxes to
accomplish a task, the image name should reflect the task AND where you are
in the series:


The advantage of this is that when it comes time to do the screen shots, you
can copy all of the English screenshots to a new directory, step through
them, and ultimately replace them in the new language WITHOUT the manual.

If you don't have images logically separated in directories, consider adding
prefixes (as seen above) so that you can separate images by
software/documentation component/functionality.

IT IS WORTH IT to embark on an image naming scheme with all of its
hassles -- renaming files, fixing broken links in documentation, etc. Better
this pain ONCE, than the repeated pain of trying to figure out the logic of
illogical names in recreating images. Non-standard names can mean lots of
back-tracking, revisiting, and reconfiguring of dialog box parameters.

That being said, the hardest part about doing the screen shots for a foreign
language is getting yourself going. It is such a tedious task.

However, anybody familiar with your software should be able to find the
dialog boxes in the new language (oriental languages excepted). If you have
a naming convention as indicated, you'll have an English "source" that you
just need to replace with something that is laid out the same in the
"target" language.

Be prepared to do some images over several times when you discover that the
GUI translation messed up dialog boxes. Undoubtedly you'll find that the
owning engineers did not look at every dialog box and did not tweak
accordingly. Your eyeballs might be the first ones looking at the
translation. Screwed up dialog boxes slows down your efforts, particularly
when you have to take the time to escalate the issue to get it fixed.

Also, a change to one term in the resource files for the GUI can affect a
whole bunch of dialog boxes. Push hard to have the GUI tested in-house and
by product experts in the target country before you start cranking out
images (but while you're working hard at getting your house in order.)

Push back HARD against any and all attempts to send things to a translator
before your house is in order even if it means delaying the release. From my
experience, there were ALWAYS enough other factors involved in the release
to delay it anyway. Even if there weren't, this is definitely a case were
you can say: "If we don't have enough time to do it right the first time,
what makes you think we'll have enough time to fix it later -- again and
again and again for each $% -at- #$@ language/release?"

In the big picture, it doesn't matter whether the translation was delayed
two weeks or a month (or longer) regardless of what Sales might say. Why?
Chances are that the critical customers in that country are already using
the English version. They will also be happier waiting a little bit longer
for an accurate translation than having a poor one delivered early that they
have to suffer with (and that you have to suffer maintaining) for the life
of the release. You can also appease them with a foreign GUI and English
documentation for a short time until the translation is ready.

Be aware, once you start translating, you get locked into lots of things
that you'd like to change but no longer can without costly side-effects. (I
have horror stories.)

On the plus side, getting your house in order in preparation for your first
translation... gets your house in order. Also, subsequent languages are
easier to tackle.

Also remember that the pay-off for this upfront work isn't necessarily today
or even in the first release, but in subsequent releases and languages.


Glenn Maxey
Voyant Technologies, Inc.
Tel. +1 303.223.5164
Fax. +1 303.223.5275
glenn -dot- maxey -at- voyanttech -dot- com

> -----Original Message-----
> From: bounce-techwr-l-58477 -at- lists -dot- raycomm -dot- com
> [mailto:bounce-techwr-l-58477 -at- lists -dot- raycomm -dot- com]On Behalf Of Laurah
> Limbrick
> Sent: Wednesday, May 02, 2001 2:38 PM
> Subject: Translating documentation/insertion of screen shots
> We are working on our first project which involves translation.
> Our current doc set is several thousand pages,
> with commensurate screen shots. The plan
> for doc translation is that we (the documentation team) will be provided
> with the translated GUI, and, using our current user docs as a guide, will
> replace all screen shots in the English doc with the translated shots by
> stepping through the foreign language GUI.


> 1. Has anyone here undertaken such a project? How did it work out?
> 2. How do you account for the lack of knowledge of the target
> language? Was this an issue?
> 3. We don't have the luxury of using a side-by-side computer approach (one
> in English, one in Spanish). Presumably this will prove to be a usability
> test of our English docs, since we'll have to step through the
> instructions.
> --
> Laurah Limbrick
> Instructional Designer
> Open Systems Technical Information Development
> CSG Systems, Inc.
> 303.200.3364


*** Deva(tm) Tools for Dreamweaver and Deva(tm) Search ***
Build Contents, Indexes, and Search for Web Sites and Help Systems
Available now at or info -at- devahelp -dot- com

Sponsored by Information Mapping, Inc., a professional services firm
specializing in Knowledge Management and e-content solutions. See or 800-463-6627 for more about our solutions.

You are currently subscribed to techwr-l as: archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot- Visit for more resources and info.

Translating documentation/insertion of screen shots: From: Laurah Limbrick

Previous by Author: RE: in Europe?
Next by Author: RE: User Manual and Online Help
Previous by Thread: 800 numbers (was RE: Translating documentation/insertion of screen shots)
Next by Thread: RE: Translating documentation/insertion of screen shots

What this post helpful? Share it with friends and colleagues:

Sponsored Ads