Mattermost serves a global audience, who might not use English as their first language.
Please keep documentation simple, effective and ready-to-translate.
- Simple
- Aim for the reading ability of an 11-year old. Use short sentences. Avoid large words.
- When things get complicated, choose clarity over completeness.
- Effective
- Focus on achieving understanding in the reader, over total correctness
- Start with what’s important, and leave less important details to the end, or omit them
- Ready-to-translate
- Avoid slang
- Avoid Western-centric, or culture-centric examples (example: instead of “fiddle with settings”, say “adjust settings”)
If you’re not sure, try using machine translation to turn your documentation into a foreign language then back into English.
Machine-Translation Example:
Here’s an example of culture-specific documentation with the word “fiddle” (meaning “to adjust repeatedly”):
There are a few configuration settings you might want to fiddle with when setting up your instance of Mattermost.
That documentation machine-translated into German and then back into English looks like this:
There are some configuration settings you could know if your instance Matter Most violin
The sentence would be more ready-to-translate to say “There are a few configuration settings you can adjust when setting up your instance of Mattermost.”
A simple trick to test documentation:
One “trick” to use to check review documentation is to ask: “How would Agent Coulson explain this concept to Thor? [1]”
We sometimes get caught in the trap of explaining things to ourselves, rather than to the intended reader. This trick helps remind us that simple, effective and ready-to-translate documentation is our end goal.

[1] We consider the Avengers movie to be part of global culture, not just Western culture. If you haven’t seen the movie yet, you really should…