Probably the most frequently asked question to the docs team at MySQL from the public is “I want to translate the manual into [insert language]”. That language can be anything from one we already have, through to some comparatively obscure suggestions.
We never summarily turn down an offer, but we do point out how big a job the process is. At over 1900 pages, the manual is no longer a small project, and where we have had translations completed, sometimes by professional translation outfits the process has taken months, and in one case over a year, to complete by a full time translation team. Even the dedicated MySQL enthusiast is going to struggle with achieving the same level of output.
Even if you could commit to a translation time of 6 months using a dedicated team, you have to keep in mind that any manual translated in this manner is not going to be up to date, for the simple reason that we make changes to the manual on a daily basis—there have been 127 changes in the last week, and some of those include more or less completely reintroduction or manipulation of the content for a chapter. It would be almost impossible to start complete translation unless the process was conducted on a very specific revision of the manual.
If the process is so difficult, why do we do it?
Well, cast your minds back a few weeks to a post I made a couple of weeks ago on translation (Foreign languages and documentation).
Reader stenone asked “Why bother translating at all?”
As an Englishman (albeit with an interest in other languages), I felt completely unable to answer that question, so instead I asked other members of MySQL to comment. The majority of staff at MySQL are not English, American or Australian, and those of us who would count English as our first language are in a minority, rather than a majority, so the question and audience were well matched.
I got a lot of good responses (thanks team!), and many of them resolved down to “we want to provide the documentation in a format that makes it readable for our customers”. That sort of answers the question—we are customer focused, and if the customers say they want a German version of the manual, we should be willing to offer that, but I still don’t think it addresses the original query.
Other suggestions were along the lines of “for our customers to use our products, they need to be able to understand how to use them”. This response is closer to the answer I was expecting. We cannot expect our users to learn English just so that they can read the manual and in turn use our product. System requirements are one thing, but having user requirements of this magnitude is hardly the way to encourage good customer relations!
We Brits have a bad track record on languages as a rule, and it’s a running joke that our attempts to speak a foreign language generally simplify down to speaking L-O-U-D-L-Y A-N-D S-L-O-W-L-Y on the basis that “Johnny Foreigner” will understand what we are saying. Apply that to a manual and we’d be approaching 5000 pages :)
In the end I think it comes down to a simple case of understanding. Imagine if MySQL, as a Swedish company, only provided their manual in Swedish?
Would it be as popular as it is now? Would MySQL have led to a massive effort around the world as people strive to learn the Swedish language, just so that we could all use MySQL in our projects?
I doubt it.
Instead, we’d all be walking around saying “Jag kan inte tala svenska”. Or we’d spend most of our time muttering “Jag förstår inte” under our collective breath while reading the manual, and probably not because of the technical content.
If you don’t understand those two phrases, then imagine how it would feel to read an entire manual!
Translations are, and will continue to be, the best way to reach the large numbers of MySQL users who do not speak English and either are unable or do not want to learn.
Comments
Documentation strategies
The pace of free software development is so fast that it is an impediment to use in itself. Isn't that a bizarre truth?!
I'm an amateur on-again off-again developer, so I often find myself starting a project, stopping for awhile to work on other stuff, then coming back to it. But often, it's like Rip van Winkle waking up after the flag (and everything under it) has changed: the library I was depending on has gone through three major version changes, and the programming style I was using is "passé": "Oh, we've moved beyond 'interfaces', 'generic functions' are much better and clearer". Ack! I can't keep up.
With documentation, mostly written by volunteers, this can be a serious problem: API documentation in particular is often out of date as a result.
In fact, the frequent complaint about lack of documentation for free software programs is usually inaccurate: most of the time there's plenty of documentation, but much of it is conflicting! Often there was an old, ugly way to solve a problem which was then replaced by a new easy way (which old-timers don't see any need to document, because it's so easy). So you wind up with smart new software and dumb old manuals.
On the other hand, the overriding concepts behind an application are usually pretty consistent even across major versions (MySQL is still going to be an SQL database, even if you've added 'transactions' or 'cursors' or whatever).
So one thing I've noticed some projects moving towards is increasing the use of automatic documentation tools: write the base document in as version-neutral a way as possible (so you don't have to constantly update it), then link into automatically generated documentation that is created from the source code comments.
For a translation effort this would help as well: there'd be less time pressure on the main manual document (because it's not changing so frequently), and the automatically-generated documentation is a much smaller project to translate). In fact, now that I think about it, I bet you could write a gettext-based system to use the old translated API with the new one so that you only have to translate the parts that have changed.
I don't know, but it does seem like there are probably a number of technical and procedural improvements that could be made.
Ambiguity and concepts without context kills the translator
I can tell you that a good translation of a MySQL manual with two thousand pages written in a technical jargon would take of technical MySQL take several years to complete for users of a minor language (i.e. a language spoken by few forty thousand or so). At the time a Greenlandic version of the MySQL manual would come out, MySQL has perhaps reached version 8 or 10. :-)
One of the most obvious difficulties that users of minor languages run into is:
(A) no equivalent set of the technical terminology, (B) very few translators that can accomplish the workload and they are perhaps geographically scattered and (C) few free software tools to assist the translators.
What is needed often seemes to be a consistent terminology for the most important hundred or two hundreds concepts used in a larger manual. A terminology would at least include (1) the concept and (2) a definition of the concept. Some further features of a good terminology would include some examples of how to use the concept (i.e. the concepts usage and how not to use it). If the concept is very close related to a specific grapical user-interface the superior terminology could include a screendump and so on.
In order to get the job done, manual translation is necessary. Perhaps the tranlators capable of getting the job done lives in seperate parts of the world. Being able to translate through a browser with some sort of workflow-management could prove to be very helpful.
Small disconnected free software projects without coupling is doomed to require the same work getting done over and over again. Many hours of inefficient translation is done due to the lack of a common, well-defined English terminology. Translation of concepts without precise a definition is prone to contain errors. Translating one concept at a time or perhaps a peculiar sentence without a context is difficult. Some free software translators may have tried to use Pootle (http://pootle.wordforge.org)? Well, it's difficult to translate strings like "%s to find blah blah", when your translation has to fit into one string. No room to make the project manager aware of the ambiguities related to that string.
Major companies will use proprietary products like MultiTerm, TermStar or XTS to provide themselves and their customers with a consistent corporate terminology. They gain clarity in communication, a corporate image and saves themselves from a lot of misunderstandings and saves a lot of time.
To give an example: Translation of the headline �Manual translation� could refer to the tiresome labour of manually translating a string and/or it could refer to translation of (software?) manuals. Ambiguity is the root of all evil in translation.