5 ms·

Next time you come across a project documented solely in Lithuanian / Japanese / Swahili, I hope you will refer to http://ericholscher.com/blog/2014/feb/27/how-

Next time you come across a project documented solely in Lithuanian / Japanese / Swahili, I hope you will refer to http://ericholscher.com/blog/2014/feb/27/how-i-judge-documentation-quality/#language http://ericholscher.com/blog/2014/feb/27/how-i-judge-documen... for insight. English is the de-facto language of the Internet (let's not discuss here how damaging that is to English as a language in general). I strongly believe that public-facing software projects should be documented in English first and foremost, with translations to other languages added as resources allow. I work for a small company in Quebec (that's the Canadian province that has a Language Police) - despite most of the team being Francophone, all our internal documentation and code docs are in English. Why would that be? Because everyone realizes, without ever really having discussed it, that it is the only efficient way to do it, if we want to collaborate with others, if we want to grow, if we want others to contribute, having everything in French would be creating unnecessary hurdles.

bajsejohannes 13y ago
Spot on! English is not my first language, but I still document and use English variable names in all my code. This includes the tinyest one-off scripts. Not only is this good if you ever want to share the code, but I find myself thinking about programming in English.
muyuu 13y ago
That depends on the potential audience of the docs I guess.
forsaken 13y ago
The article isn't saying to write things in another language as canonical, it's just saying put the language in the URL so later you can add other languages without breaking the URL. I think that is what you are advocating in part of your response.
green7ea 13y ago
I'm a consultant in Quebec and I've seen too many companies document code in French. Sometimes variable and function names are in a mix of French and English. The worse is when your errors and exceptions are in French: you get very confused international clients. English reading and writing skills are a MUST for programmers and I envy your working in what sounds like a much nicer code base.
- cbab 13y ago
  Absolutely! Codebases in "franglais" are terrible. Also, when documenting such codebases, I cringe whenever I see public APIs with mixed language members.
- Moru 13y ago
  Germany has the same problem. Many haven't even learned to read english since everything else in germany is dubbed. Very frustrating. Here in sweden most things are written in english though so no problem. No one even thinks twice before writing comments in code. English is the standard.
zdw 13y ago
Specifying the language with an /en/ in the URL isn't a major inconvenience, and allows for future expansion at the cost of 3 additional characters in an URL. Including it says "I planned ahead and worked intentionally", which shows you care, which fundamentally is what this article is driving at. And yes, documentation should generally be in English first - it's the current language of science and tech, just as it was when French, German, Latin, Arabic, and Greek proceeded it.
- chc 13y ago
  Adding an /en/ when you decide to translate the documentation isn't a major inconvenience either. I would rather add it when it's relevant than include something that will probably never be anything but noise. This is pretty much the same reason I don't put in a bunch of non-functioning UI controls that will hopefully have features attached in the future — my interface is meant to be practical, not aspirational.
  - Moru 13y ago
    What about controlling the language from a cookie? Link to www.example.com/v1.5/import.html and end up with whatever language your browser specifies. A drop-down with links to all possible languages for this page so you can choose the one that fits you best. This enables you to have an incomplete translation in case you just don't have the resources to translate your whole documentation at once.
- pseut 13y ago
  Adding /en/ to the URL creates an expectation that there are translations in other languages.
thoward37 13y ago
I have to say that I completely disagree with this perspective. Yes, currently our 'lingua franca' of business and technology is English, but I feel that is a problem, not a solution. It's a problem because it unfairly advantages native English speaking people in business. It creates a barrier of entry to people who did not learn English from an early age, along with their native language. It makes it much harder for those people to be part of business, technology, and open source. It degrades the quality of communication and work-output by forcing non-native speakers to express themselves in English. Does being a good engineer imply being good at spoken natural languages? I have met some brilliant engineers in China who are barely functional in English. If you were to interact with them purely in English, you would think you're talking to a 5 year old, based on the language alone. Some of the engineers I've met in China aren't even that capable with English, but are wonderful developers writing interesting things. Sometimes they created documentation in Chinese, sometimes in English. Guess which one they were able to express their ideas in more clearly? Chinese. When you write, you should write in your native language, and express your idea to the best of your ability. Then, if you want to translate that to other languages later, to make it more accessible to others, do that as a separate task. Maybe hire a professional technical translator to do that work. You gave this example of coming across a page written in Lithuanian or Japanese, presuming of course that you're not a native speaker of those languages. Fine, that's exactly how every Chinese native speaker feels when they come across a page of English text, every day of their life as a developer... but they figure it out, even with terrible language skills. You know why? Not because "English is the language of business" but because they just want to learn about the content, and aren't going to try to force you to write it in Chinese so they can do that. If all those pages were in French they would figure that out too. With the attitude you expressed above, the main people who benefit from this are native English speakers. Anyone else is still in the 2nd language boat. So then of that group, you advantage people with a talent for natural languages, or who are wealthy enough, as a child, to have access to education resources to learn another language. As a former English teacher in China, I promise you that this is a huge economic divide. The kids who can afford to learn English succeed, those who can't, don't. That's fucked up, and not at all a reasonable way to approach business. A good engineer should not be left with no opportunities because they grew up poor, or have no real talent learning foreign languages. In business, such concerns about equality and fair access might not be very important, because unfair advantages and competition are what much of business is all about... but in open source, and in modern businesses that are learning from the open source model, I think being concerned with inclusiveness is paramount. So yes, you might have to struggle through reading something like this: https://github.com/be5invis/youki/blob/master/README.yk https://github.com/be5invis/youki/blob/master/README.yk ... but it doesn't take much to punch "Youki 是一个文档生成语言，其具备完整的编程特性和完备的宏特性，使之可作任意复杂的文章。Youki 是完全开放源码的，依照 MIT 协议发布。" into Google Translate (or use the auto-translate features of Chrome). Now we can all get on with our lives and use be5invis's cool documentation generation tool. Would you prefer to exclude him and his work from our community by forcing him, a Chinese square-peg through some English speaking round-hole? Personally, I'm willing to do a little extra work to understand him in his own language. I also appreciate deeply that he has to do that work constantly, in order to read my code/docs in my native language.
hrktb 13y ago
I used to think the same. But as for any rule, there are exceptions. Documenting a Swahili project dealing with parsing official Swahili resources may not be best done in english, just translating every idiomatic notion into english would be a waste of time, effort and won't help anyone. System that only make sense in a specific context should be OK to be documented in the most appropriate language.

bajsejohannes 13y ago

Spot on! English is not my first language, but I still document and use English variable names in all my code. This includes the tinyest one-off scripts. Not only is this good if you ever want to share the code, but I find myself thinking about programming in English.

muyuu 13y ago

That depends on the potential audience of the docs I guess.

forsaken 13y ago

The article isn't saying to write things in another language as canonical, it's just saying put the language in the URL so later you can add other languages without breaking the URL. I think that is what you are advocating in part of your response.

green7ea 13y ago

I'm a consultant in Quebec and I've seen too many companies document code in French. Sometimes variable and function names are in a mix of French and English. The worse is when your errors and exceptions are in French: you get very confused international clients. English reading and writing skills are a MUST for programmers and I envy your working in what sounds like a much nicer code base.

cbab 13y ago
Absolutely! Codebases in "franglais" are terrible. Also, when documenting such codebases, I cringe whenever I see public APIs with mixed language members.
Moru 13y ago
Germany has the same problem. Many haven't even learned to read english since everything else in germany is dubbed. Very frustrating. Here in sweden most things are written in english though so no problem. No one even thinks twice before writing comments in code. English is the standard.

zdw 13y ago

Specifying the language with an /en/ in the URL isn't a major inconvenience, and allows for future expansion at the cost of 3 additional characters in an URL. Including it says "I planned ahead and worked intentionally", which shows you care, which fundamentally is what this article is driving at. And yes, documentation should generally be in English first - it's the current language of science and tech, just as it was when French, German, Latin, Arabic, and Greek proceeded it.

chc 13y ago
Adding an /en/ when you decide to translate the documentation isn't a major inconvenience either. I would rather add it when it's relevant than include something that will probably never be anything but noise. This is pretty much the same reason I don't put in a bunch of non-functioning UI controls that will hopefully have features attached in the future — my interface is meant to be practical, not aspirational.
- Moru 13y ago
  What about controlling the language from a cookie? Link to www.example.com/v1.5/import.html and end up with whatever language your browser specifies. A drop-down with links to all possible languages for this page so you can choose the one that fits you best. This enables you to have an incomplete translation in case you just don't have the resources to translate your whole documentation at once.
pseut 13y ago
Adding /en/ to the URL creates an expectation that there are translations in other languages.

thoward37 13y ago

I have to say that I completely disagree with this perspective. Yes, currently our 'lingua franca' of business and technology is English, but I feel that is a problem, not a solution. It's a problem because it unfairly advantages native English speaking people in business. It creates a barrier of entry to people who did not learn English from an early age, along with their native language. It makes it much harder for those people to be part of business, technology, and open source. It degrades the quality of communication and work-output by forcing non-native speakers to express themselves in English. Does being a good engineer imply being good at spoken natural languages? I have met some brilliant engineers in China who are barely functional in English. If you were to interact with them purely in English, you would think you're talking to a 5 year old, based on the language alone. Some of the engineers I've met in China aren't even that capable with English, but are wonderful developers writing interesting things. Sometimes they created documentation in Chinese, sometimes in English. Guess which one they were able to express their ideas in more clearly? Chinese. When you write, you should write in your native language, and express your idea to the best of your ability. Then, if you want to translate that to other languages later, to make it more accessible to others, do that as a separate task. Maybe hire a professional technical translator to do that work. You gave this example of coming across a page written in Lithuanian or Japanese, presuming of course that you're not a native speaker of those languages. Fine, that's exactly how every Chinese native speaker feels when they come across a page of English text, every day of their life as a developer... but they figure it out, even with terrible language skills. You know why? Not because "English is the language of business" but because they just want to learn about the content, and aren't going to try to force you to write it in Chinese so they can do that. If all those pages were in French they would figure that out too. With the attitude you expressed above, the main people who benefit from this are native English speakers. Anyone else is still in the 2nd language boat. So then of that group, you advantage people with a talent for natural languages, or who are wealthy enough, as a child, to have access to education resources to learn another language. As a former English teacher in China, I promise you that this is a huge economic divide. The kids who can afford to learn English succeed, those who can't, don't. That's fucked up, and not at all a reasonable way to approach business. A good engineer should not be left with no opportunities because they grew up poor, or have no real talent learning foreign languages. In business, such concerns about equality and fair access might not be very important, because unfair advantages and competition are what much of business is all about... but in open source, and in modern businesses that are learning from the open source model, I think being concerned with inclusiveness is paramount. So yes, you might have to struggle through reading something like this: https://github.com/be5invis/youki/blob/master/README.yk https://github.com/be5invis/youki/blob/master/README.yk ... but it doesn't take much to punch "Youki 是一个文档生成语言，其具备完整的编程特性和完备的宏特性，使之可作任意复杂的文章。Youki 是完全开放源码的，依照 MIT 协议发布。" into Google Translate (or use the auto-translate features of Chrome). Now we can all get on with our lives and use be5invis's cool documentation generation tool. Would you prefer to exclude him and his work from our community by forcing him, a Chinese square-peg through some English speaking round-hole? Personally, I'm willing to do a little extra work to understand him in his own language. I also appreciate deeply that he has to do that work constantly, in order to read my code/docs in my native language.

hrktb 13y ago

I used to think the same. But as for any rule, there are exceptions. Documenting a Swahili project dealing with parsing official Swahili resources may not be best done in english, just translating every idiomatic notion into english would be a waste of time, effort and won't help anyone. System that only make sense in a specific context should be OK to be documented in the most appropriate language.