Mattermost is an open source enterprise messaging and team collaboration application. It’s like Slack, but with excellent Markdown support.In fact, Mattermost provides exactly the type of Markdown support you want to see in a messaging application. Mattermost is an open source enterprise messaging and team collaboration application. It’s like Slack, but with excellent Markdown support.In fact, Mattermost provides exactly the type of Markdown support you want to see in a messaging application. Mattermost markdown autolinking inconsistencies #7407. Closed ryantm opened this issue Sep 7, 2017 6 comments Closed mattermost markdown autolinking. Summary Image/link preview works with an external image proxy (atmos/camo) only when inline markdown is used. Steps to reproduce Setup and enable an external image proxy: atmos/camo with Mattermost 5.13 Paste a image link as inline markd.

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.

Mattermost Link Formatting

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”):

That documentation machine-translated into German and then back into English looks like this:

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]”

The Magic Of Mattermost Markdown - Communicate More Effectively

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.

[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…

This is probably a coincidence, but after Mattermost announced markdown support last week, Slack announced the same feature yesterday.

Markdown is an easy-to-read, easy-to-write plain text format that can optionally be converted to HTML, which is commonly used in the open source community for documentation.

Last Thursday, Mattermost wrote a blog post on creating richly formatted posts with headings, lists, code blocks, tables and a board range of font formatting.

Yesterday, Slack announced the same thing.

Again, it’s almost certainly coincidence. Also, it’s likely Slack had the idea long before Mattermost–because it wasn’t our idea.

Two months ago, markdown support in Mattermost started as a community feature idea that amassed dozens of votes (though given their size, Slack probably heard the same idea hundreds of times by now…).

Line Breaks

What’s striking here is the power of open source software to respond to community feedback.

A small group of people openly contributing ideas and energy can build faster than a company with hundreds of millions of dollars of funding.

It’s an amazing feeling to work with smart, like-minded individuals from around the world to improve a product that we use every day.

Want that feeling?

Get involved with the Mattermost open source project at http://mattermost.org.

PS: Yes, we’re currently accepting pull requests to update Mattermost’s Slack import feature to support Slack’s newly announced markdown support.