Documentation Guidelines

Mattermost serves a global audience, who might not use English as their first language.

Please keep documentation simple, effective and ready-to-translate.

1. Simple
   1. Aim for the reading ability of an 11-year old. Use short sentences. Avoid large words.
   2. When things get complicated, choose clarity over completeness.
2. Effective
   1. Focus on achieving understanding in the reader, over total correctness
   2. Start with what’s important, and leave less important details to the end, or omit them
3. Ready-to-translate
   1. Avoid slang
   2. 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…