Aim for the reading ability of an 11-year old. Use short sentences. Avoid large words.
When things get complicated, choose clarity over completeness.
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
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.
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? ”
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
 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…