Documentation Guidelines

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

To keep Mattermost “obvious” to users, please keep documentation and on-screen help 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. Effective
    1. Start with what’s important, and leave less important details to the end, or omit them
    2. Focus on achieving understanding in the reader, over total correctness or completeness.
  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.”

Testing our documentation:

One “trick” to use to review documentation is to ask: “How would Agent Coulson explain this concept to Thor? [1]”

Agent Coulson takes complex ideas and explains them simply and effectively. Thor isn’t from earth, so we have to filter out ideas that are culturally specific–fiddles, baseball, wedding rings, etc.–and that makes things easy-to-translate.

As a communications company, clarity matters. If you see documentation missing these guidelines we’d gladly take bugs and pull requests.

Mattermost documentation should sound like Agent Coulson explaining something to Thor
Mattermost documentation should sound like Agent Coulson explaining something to Thor

[1] Agent Coulson and Thor are characters from the movie “Avengers”, which we consider to be part of global culture, not just Western culture. If you haven’t seen the movie yet, you really should…