In a previous post, I discussed the problems we encountered when considering translating our entire MediaWiki-based documentation suite. I talked about how to get content out of the wiki for translation, and then get translated content back to our users.
In this post, I want to discuss translation and globalization requirements more generally, and how our small, agile doc team, working in MediaWiki, handles each requirement. Fulfilling these requirements results in lower translation costs and easier translation:
- Provide a medium for the translated documentation that accommodates text expansion
- Use preformatted styles
- Minimize the amount of text to be translated
- Minimize content churn
- Write in a style that allows easy translation
A medium for the translated documentation
Full marks on this requirement. Delivering the translated documentation in a Japanese sister wiki will work well. We also integrate our documentation with our software as JavaHelp, and there are no issues with text expansion in either medium.
Again, no issues here. MediaWiki provides heading and formatting styles that are preserved in the XML export, so no one needs to waste time on formatting the translated text.
Minimizing the amount of text
Here’s where the slope gets slippery. Shorter takes longer. With a small team under constant pressure to keep up with agile development, it’s hard to find the time to write concisely. It’s also hard to find time to deal with legacy content.
Minimizing the amount of documentation makes sense for the English version as well as translations. And it makes for easier maintenance, too.
There are two opportunities for content churn: during development, and after the release.
During development. Ideally, we’d provide an initial drop to the translators at Beta, and pledge that we’re something like 80% complete. But in agile development, features are constantly refined as a result of testing and customer feedback. Features are added to the release as resources permit, and as product management becomes aware of new customer requirements. With a small team, we work on documenting features right up to the release date. Our development, test, and product management teams review the docs whenever they have time. And as perfectionists, we just can’t resist editing… and re-editing. An agile wiki is a highly flexible creature. But churn is its middle name.
After the release. We continue to fix problems we find in the English documentation, and our customers can edit too. That’s the whole point. Presto: The translation is out of date.
Easily translatable style
We’ve adopted a casual, conversational, humorous style as an attempt to engage our users. But this type of style can be difficult to translate. It can also be difficult for ESL readers to understand. And even non-North American English speakers might find our humor… unfunny.
Here are just a few things we need to do:
- keep sentences short
- simplify the grammatical structure
- avoid idioms and jargon
- create a more extensive glossary
- avoid text in graphics
So, in our spare time, we’re updating our style guide, and when that’s done, we’ll be creating a review checklist for translation and globalization requirements. Our style guide will be funny, because so far, no one has asked us to translate it.
I found the article “Maintaining Documentation Across Several Languages” helpful in my research.