Hello,

I have the following situation: a very long and technical manual
(hundreds of pages) about a complex piece of software that is
constantly changed and (hopefully) improved. Each chapter is another
Word document.

Problems and questions:
* Each document has to be translated from Dutch to French. Some of the
files are already translated, but not all.
* Some of the existing translations are outdated.
* Most images are screenshots, those have to be translated too. The
person who translates doesn't have access to the software the manual
describes.
* Images: should they be inside the document or external files?
* The translator doesn't have the technical knowledge the original
authors have, and she doesn't have a lot of time.
* There are about 4 people working on the manual, not always
simultaneous.
* Each time a part of the manual is updated, the changed paragraph is
mailed to the translator, who translates, sends it back, and the author
copies the translated part in the final document. Or is there a better
method?
* The manual is usually two versions behind the software it describes.

In short: maintainability is becoming a problem.
How is this done in "the real world"?

--
Amedee Van Gasse

Gosh, Amedee, this sounds like a nightmare - I'm not surprised you are two
versions behind!

I think your first priority is to get proper resourcing for the translation.
You need people with the right technical background, and not trying to do
this part-time around other activities. They should be maintaining
cross-language glossaries as a first requirement to translating the
text/screenshots.

Ideally you would complete the manual first, and then the translation should
be one-shot. At least aim to have only a single pass on each chapter and for
the translators to get sight of the whole draft early in the game. Good
translation firms will be able to work within your template and the text
should need only minimal (re)formatting after they have finished. It seems
to me translation of isolated paragraphs is just certain to produce errors.
If only some paragraphs have changed, then send a revision-marked file for
translation.

In this situation I would definitely keep the screenshots linked, even
though that means some extra file and folder management. If you do this is
should be possible to do automatic replacements of the Dutch versions with
the French ones in the translated version of the files which should save
some copy and paste time.

I wish you the very best of luck :-)

--
Margaret Aldis - Microsoft Word MVP
Syntagma partnership site: http://www.syntagma.co.uk
Word MVP FAQ site: http://www.word.mvps.org


"Amedee Van Gasse" wrote in message
...
Hello,

I have the following situation: a very long and technical manual
(hundreds of pages) about a complex piece of software that is
constantly changed and (hopefully) improved. Each chapter is another
Word document.

Problems and questions:
* Each document has to be translated from Dutch to French. Some of the
files are already translated, but not all.
* Some of the existing translations are outdated.
* Most images are screenshots, those have to be translated too. The
person who translates doesn't have access to the software the manual
describes.
* Images: should they be inside the document or external files?
* The translator doesn't have the technical knowledge the original
authors have, and she doesn't have a lot of time.
* There are about 4 people working on the manual, not always
simultaneous.
* Each time a part of the manual is updated, the changed paragraph is
mailed to the translator, who translates, sends it back, and the author
copies the translated part in the final document. Or is there a better
method?
* The manual is usually two versions behind the software it describes.

In short: maintainability is becoming a problem.
How is this done in "the real world"?

--
Amedee Van Gasse

Margaret Aldis shared this with us in
microsoft.public.word.docmanagement:

Gosh, Amedee, this sounds like a nightmare - I'm not surprised you
are two versions behind!

Margaret,

To make matters even worse: some of our customers (local branches of
multinational companies) demand english manuals...

Even with proper translation, we would be one or two versions behind,
because the actual writing of the manual is also done between other
stuff.

I think your first priority is to get proper resourcing for the
translation. You need people with the right technical background, and
not trying to do this part-time around other activities. They should
be maintaining cross-language glossaries as a first requirement to
translating the text/screenshots.

In an ideal world, yes. However it is not possible to find someone with
the right technical background AND has the skills to translate AND has
the time to do it. From these 3 requirements, choose *maximum* 2.

Ideally you would complete the manual first, and then the translation
should be one-shot. At least aim to have only a single pass on each
chapter and for the translators to get sight of the whole draft early
in the game. Good translation firms will be able to work within your
template and the text should need only minimal (re)formatting after
they have finished. It seems to me translation of isolated paragraphs
is just certain to produce errors. If only some paragraphs have
changed, then send a revision-marked file for translation.

We tried a "translation firm" once. The quality was very poor (both in
translation errors as in contextual errors), so now it is done
in-house. That means someone who has to do it part-time between other
work. The same goes for the original version of the manual. 5% of our
time would be a *very* optimistic estimate.

Imagine this: a new module is programmed for the software. When the
programmers are almost done, I and my collegues get to play with it
(test it) for a week so we get to know it. Meanwhile we have to support
existing customers. If we're lucky, we can write the documentation for
the new module a few weeks (or even months!) later. But by that time it
is already "in the field". And by the time we write a manual, version
1.1 of the new module is ready for testing.

And then translation has to start! By the time this is done, we have a
french manual version 1.0, a dutch manual version 1.1 and a software
version 2.0...

In this situation I would definitely keep the screenshots linked,
even though that means some extra file and folder management. If you
do this is should be possible to do automatic replacements of the
Dutch versions with the French ones in the translated version of the
files which should save some copy and paste time.

OK, we're already doing that.

I wish you the very best of luck :-)

Thank you, we need it. :-)

--
Amedee Van Gasse

Hi Amedee

I honestly think you should look for a better translation company with the
right specialisations, and perhaps while you are about it outsource the
manuals. Writing user documentation is a full-time, professional activity,
and it needs to be interlocked properly into the development lifecycle - if
the software needs a user guide, then the code and user guide *both* need
testing and approval before the product gets released - in other words, you
should be testing the doc, not writing it, in the week you get to "play"
with a new module. Letting users work with out-of-date and inaccurate
manuals just reduces user respect for the doc, the product and the company -
they'll never bother to look anything up and will put extra pressure on
support.

I'm sure you know all this and just need to find the right levers to pull to
start educating your managers :-) You could try Googling "user
documentation" and "software development process" to get some best practice
papers. Not sure I can help any more where the baseline doc is in Dutch, but
if you want to mail me off-line I may be able to give you some contacts.

--
Margaret Aldis - Microsoft Word MVP
Syntagma partnership site: http://www.syntagma.co.uk
Word MVP FAQ site: http://www.word.mvps.org


"Amedee Van Gasse" wrote in message
...
Margaret Aldis shared this with us in
microsoft.public.word.docmanagement:

Gosh, Amedee, this sounds like a nightmare - I'm not surprised you
are two versions behind!

Margaret,

To make matters even worse: some of our customers (local branches of
multinational companies) demand english manuals...

Even with proper translation, we would be one or two versions behind,
because the actual writing of the manual is also done between other
stuff.

I think your first priority is to get proper resourcing for the
translation. You need people with the right technical background, and
not trying to do this part-time around other activities. They should
be maintaining cross-language glossaries as a first requirement to
translating the text/screenshots.

In an ideal world, yes. However it is not possible to find someone with
the right technical background AND has the skills to translate AND has
the time to do it. From these 3 requirements, choose *maximum* 2.

Ideally you would complete the manual first, and then the translation
should be one-shot. At least aim to have only a single pass on each
chapter and for the translators to get sight of the whole draft early
in the game. Good translation firms will be able to work within your
template and the text should need only minimal (re)formatting after
they have finished. It seems to me translation of isolated paragraphs
is just certain to produce errors. If only some paragraphs have
changed, then send a revision-marked file for translation.

We tried a "translation firm" once. The quality was very poor (both in
translation errors as in contextual errors), so now it is done
in-house. That means someone who has to do it part-time between other
work. The same goes for the original version of the manual. 5% of our
time would be a *very* optimistic estimate.

Imagine this: a new module is programmed for the software. When the
programmers are almost done, I and my collegues get to play with it
(test it) for a week so we get to know it. Meanwhile we have to support
existing customers. If we're lucky, we can write the documentation for
the new module a few weeks (or even months!) later. But by that time it
is already "in the field". And by the time we write a manual, version
1.1 of the new module is ready for testing.

And then translation has to start! By the time this is done, we have a
french manual version 1.0, a dutch manual version 1.1 and a software
version 2.0...

In this situation I would definitely keep the screenshots linked,
even though that means some extra file and folder management. If you
do this is should be possible to do automatic replacements of the
Dutch versions with the French ones in the translated version of the
files which should save some copy and paste time.

OK, we're already doing that.

I wish you the very best of luck :-)

Thank you, we need it. :-)

--
Amedee Van Gasse