Documentation Languages – Writing Documentation in Non-English Languages

documentation

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.

Best Answer

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 sense1. Yes, this means you may have to provide the same documentation translated into multiple languages.

1 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.

Related Topic