Internationalization and writing guidelines

[alangdm]

Code of conduct

• I agree to follow this project's code of conduct.

Description of request

A follow up to a discussion in the slack (there was no pertinent issue template so I just used a random one)

I think we need to consider strategies to reach non-English speakers in the long term with the docs site.

Having human-translated documents would obviously be ideal as, at least in my experience, having hand-written docs in many languages definitely improves the reach for the technology. For example, I have two versions of the same Shadow DOM article, one in English and one in Japanese, but the Japanese one has over 5 times the visit count. I think it's mainly because there’s pretty much zero Shadow DOM content in Japanese. But then again, we don’t even have English docs yet so human translations are not really something feasible for the time being in my opinion.

However, I think we could at least follow some sort of writing guidelines to make sure the content doesn’t get butchered when going through machine translators. Even just avoiding the usage of idioms and other contextually or culturally dependent wording can make a big difference while we figure out if providing human translations is going to be part of our roadmap at some point.