TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
Elizabeth OShea reports that her client produces documentation for <<... a
router and its associated software. Part of this documentation is
autogenerated from a database that developers periodically update with new
features or changes to existing features. The other half of the
documentation is created manually and maintained outside the database.
Currently they cannot put the manually created docs into the database: there
are a number of programming issues around the db (an internal tool only)
that they haven't the resources to fix. Once the hybrid docs reach a certain
stage in the production process they are saved to VSS.>>
VSS = "Visual Source Safe"? Can't comment on that part of the process, or
the database itself, but this strikes me as a situation that calls for
hiring an external consultant to fix the database problems. Solve them once,
then benefit from having a single documentation set in future. I bet you
could do a quick cost-benefit analysis that would make this case
persuasively. Running two systems in parallel is difficult and can lead to
<<They need to localise this set of documents into French. A reseller in
France has offered to do this localisation.>>
A reseller might be a good choice, since they supposedly know their audience
well. On the other hand, that's not a safe assumption, and localisation
isn't something "sellers" can generally do well, so you'll want to carefully
confirm their expertise before accepting their offer. Among other things,
consider your market carefully; the French spoken in France isn't the same
as the French spoken elsewhere (e.g., Quebec, Africa). This is essentially
the same problem you face with British, Canadian, Australian, and U.S.
English, but it comes down to making sure you either produce "least-common
denominator" French or a version that targets your primary French audience.
<<Should they put the localised information into the database, specify that
it's the French docs, and then pull them when they need French
That would make sense, except that your introduction suggests you can't add
anything else to the database. That being the case, your suggestion doesn't
seem likely to work. It's particularly problematic given that you don't have
anyone on staff who can ensure that the right information goes into the
right part of the database. This is a nontrivial problem you'll have to
solve, and solve soon.
<<Follow-up question: how do they update the info in the database - none of
the developers speak fluent French, and neither writer can proofread it>>
That's where you need an expert of some sort. I'm guessing that you'll end
up with an experienced localisation contractor--ideally one who has the same
database setup so they can do the work for you--then use your reseller or
someone more qualified to do a reality check on the results. If France is
going to be your primary market, I can probably put you in touch with a
translator who could do this work (quality assurance) on contract.
<<Should they have the documents localised every time there's a new software
release? [Issue: updates happen quite frequently]>>
Of course. If the updates are frequent, then whatever system you develop for
managing your English releases must be capable of managing the French
releases equally well. In my experience, the French are just as irate about
getting second-rate documentation as anyone else.
<<How do they control the extra information the localisers have to add? The
embedded web on the gateway [its user interface, which will remain in
English] is not being localised, so the French documentation will have to
elaborate on what the English on the embedded web means. Obviously many
terms are already defined but, for example, they will have to create a table
giving the French equivalent to the English labels on the LED lights on the
Given that you're going to be localizing all the software at all, why not
localize the gateway too? If you produce the router yourselves, this is
simple because you'll already have the translations in the documentation.
For example, somewhere you'll have a definition of the "Error" light that
provides the word "Faute" or "Panne" or some such plus translation of the
English discussion of this light; on the diagram that shows the status
lights, you'll already be showing the English label that defines the purpose
of each light, and it's trivial to add the French definition there too.
If someone else produces the router, the odds are good that if they sell it
in the European Community market they have a French version of the router,
and your reseller can provide details on the terms used for that version. If
not, you might recoup some of your localisation costs by selling a set of
stick-on labels that clients can paste on the router. Never force someone to
use a different language when there's an easy solution. How would you like
to have to use the Japanese terms for the controls on your Sony stereo or
<<I welcome tips about the localisation process, because this is the first
time this client has localised anything.>>
One biggie, hinted at earlier, is that whoever does the localisation should
either provide their own guarantee of quality control (e.g., certifying that
they've tested the translation on the actual users or representative locals
who can speak for those users), or else should work with someone you appoint
to do that quality control. One of the big parts of this quality control is
making sure that the English matches the French, and that takes a bilingual
--Geoff Hart, geoff-h -at- mtl -dot- feric -dot- ca
Forest Engineering Research Institute of Canada
580 boul. St-Jean
Pointe-Claire, Que., H9R 3J9 Canada
"User's advocate" online monthly at
Hofstadter's Law--"The time and effort required to complete a project are
always more than you expect, even when you take into account Hofstadter's
Acrobat & FrameMaker Seminars: PDF Best Practices, FrameMaker-to-Acrobat
Advanced Techniques, FM Template Design, Single Sourcing with FrameMaker
in Brussels (Oct), and in Montreal & Dallas (Dec): http://www.microtype.com/1
Check out the new release of RoboDemo, our easy-to-use tutorial software.
Plus, buy RoboHelp Office in August and save $100 with our mail-in rebate.
Get details and download free trial versions at http://www.ehelp.com/techwr-l
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 http://www.raycomm.com/techwhirl/ for more resources and info.