Do you write Documentation in a language other than English?

Question

A couple of months ago I moved to Germany. Taking some projects on my own, I've recently had the opportunity to develop with a company-based framework, that was very well documented, but in German. My German is pretty good, however my programming terminology is somewhat lacking.

Long story short, I was wondering, how common is it to document code in a language other than English?

Sorry to seem English-centeric but it seems like a bad habit.

Answer 1

Personally, I tend to write all variable/function/class names, comments and documentation in English. And no, it's not my native language (Dutch is).

There are several reasons for this:

• As others have said, English is the de facto lingua franca of programming. If you're working in an international team (with coworkers, foreign students/teachers, or other contributors to an open source project) it's usually the obvious choice, even if none of the people involved are native speakers.
• Even for my personal projects that I haven't shared with anyone, I use English. You never know when you might want to distribute something (e.g. by turning it into an open source project, or just sending a copy to a friend).
  • This is especially the case if you might want to distribute the entire revision history by publishing it somewhere, since this way it's more useful without having to go back and translate everything.
  • Even for projects I have no intention of ever sharing with anyone, it's English all the way. Best to keep up the habit.
• Much of programming and computer jargon is based on English. Even when talking to other native Dutch speakers about these topics, I tend to throw in a lot of English words and phrases. If your comments are going to contain English anyway, they might as well contain only English.
• Dutch comments often just look wrong somehow. Out of context, maybe.

For non-programming related documentation (e.g. user docs) it really depends on the intended audience. There are definitely cases where providing documentation in non-English languages makes sense, but I think there are very few cases where not providing English documentation makes sense¹. Yes, this means you may have to provide the same documentation translated into multiple languages.

¹ Even if the product being documented is tightly bound to a geographical region where English is not one of the primary languages, that doesn't necessarily excuse a lack of English docs. For example, tax software for the Dutch market at first look wouldn't seem to need non-Dutch documentation. Until you consider foreigners living and working here, perhaps needing all the help they can get to figure out an unfamiliar tax system. And (western) foreigners living here are much more likely to know English than any other non-Dutch language -- though in this particular example Arabic and Turkish docs might be useful too due to relatively large immigrant communities from those regions.

Answer 2

Documentation for programmers or documentation for users?

Anyways, it doesn't matter. Yes in both cases. For users, naturally, in whatever language is required. For programmers, english is lingua franca nowadays, but it still goes.

Why on earth would it be a bad habit? Coming from an english speaking country perhaps? ;) For many (most of the world's population) english is still a foreign language.

Answer 3

All aspects of documentation depend on its target audience — including language.

End-user docs should be in the language of the end user: her native tongue, the right terminology, relevant level of detail, etc. For products you sell in other countries you may need to have end-user documentation professionally translated to several languages.

Developer docs can be kept in a language other than English. Non-coders could need to consult it. Coders may have a weak grasp of English, which could make English docs written by them incomprehensible and even incorrect. We did keep internal technical docs in Russian when I worked in Russian teams. This worked well. Nobody had language-related problems, and business terminology blended in well, too.

If your product is built by an international team (commercially or by community), you have to keep your internal documentation in the common language of the industry. Today this is English; in 16th century you'd use Latin. There's virtually no choice.

Our current team speaks mostly Russian, but our documentation and bugtacker is in English, and customers from around the world use it to talk to us and to each other. When I worked in a company staffed with American, Japanese and Russian people, our business requirements were mostly in Japanese and English, most developers spoke Russian, and most operations people spoke Japanese. Of course, we used English for all technical communication and documentation.

Answer 4

I write my documentation in whichever language the customer wants, if I know it. If not, I default to either my own language or English, depending on circumstances (whichever is easier for me and/or the customer to get translated).

Customers deserve nothing less.

Answer 5

I think it's an awful habit not to write code or documentation in English.

In fact I am German and I profoundly hate code written and documented in German. There is quite a lot of "native" terminology to pick up, which is mingled with English terminology. When you look into the code, you have English framework and library classes/functions/constants along with custom German ones. The result is not only quite ridiculous, but also hard to read, because you have to switch languages in your head all the time.

English is the lingua franca of programming. There's nothing anybody can do about it. And why would you? It's a great thing our community has one. But if you choose not to use it, you lock yourself out from the community. You lock yourself into the decision, that only you and others sufficiently skilled in your language can work with your code.

Native speakers can hardly understand that, because whenever you have a problem, you can just google it. If you google for the same problem in another language, you have a fraction of these results, the best of them giving you a short summary of some information only available in English. This is also why I refuse to use localized software, because I got sick of wasting time trying to translate menu items back and forth to be able to use an English tutorial and a German software together.

Learning English to a degree where you can use it to read and write code and documentation is very easy (at least for native speakers of an Indo-European language). Supposing you daily use 3rd party libraries, which mostly are open source code (unless you're maintaining some business software that was written by dinosaurs), and also take some time to read some of the code and docs, this happens automatically.

And also I think of every language as yet another key to untranslatable wisdoms. So if anybody claims, he has no time to learn English, is probably a sign of short-sightedness, if not even ignorance.

Answer 6

"how common is it to document code in a language other than English?"

In the countries like France which are underdeveloped in everything related to IT and software development in general and especially project management, it happens very frequently.

There are a few large companies which are working with developers from other countries. Those companies have a policy which makes it mandatory to use English everywhere, from the names of files, classes and methods, to the technical (developer oriented) documentation.

Huge number of companies, instead, use French, or a mix of French and bad English (or more often a mix of bad French and bad English). Either they never hire developers outside France, or if they do, bad things happen, since the foreign developers cannot work on the existent codebase.

Do you write Documentation in a language other than English?

Hopefully not. Never. In fact, using languages other than English can cause several problems:

• By using local language rather than English, you forbid yourself from hiring English-spoken people who don't know the local language. On the opposite, by making English mandatory, you block yourself from hiring developers who don't know English, that is to say the most incompetent ones. And yes, in France, many developers don't know English enough to use online resources like English version of MSDN or StackOverflow.
• Whenever you work with foreign partners, there might be problems if they need the technical documentation.
• If you have source code in English (and if not, you have your place in DailyWTF stories) but your documentation is in another language, the following problem arises: would you translate some terms between source code and documentation, or would you mix English and another language in documentation? In the first case, if several people are working on the same project, they may translate terms differently, which will make it very difficult to understand the documentation later.
• If one day, you'll decide to open source the project, what will happen to the documentation? Would you translate it? Or hide it from the community?
• It can happen that you decide to sell your software product to another company, including foreign one. If your documentation is in local language, you can't do that (or the price will be much lower, since the product will lack correct, usable documentation).