Mattermost Community Content Guidelines¶

Goal¶

Success in marketing means more people in our target audience discover, understand, and unlock the benefits of Mattermost for their organizations through faster, larger, more effective deployments.

Objectives¶

In order to achieve this overriding goal, we must:

1. Increase awareness of Mattermost as a solution to key challenges facing organizations as measured by new visits to mattermost.com
2. Reduce the time for organizations to decide on deploying open source and commercial versions through educational content on product value
3. Increase the number of organizations deploying Mattermost swiftly, efficiently and effectively
4. Increase the compellingness and trustworthiness of Mattermost product and marketing content as measured by increase in return visits

The biggest uplift to inbound marketing will come from being featured in online publications such as The Hacker News.

Principles¶

In order to achieve these goals, our writing must be:

1. Magnetic to IT. We need headlines and openings that draw in IT audiences (these include Linux admins, security experts, directors of end-user computing, CIOs). Bear in mind that, although they work in IT, these audiences are typically more interested in the business benefits of technology than technical features.
2. Appealing to secondary audiences. These include open source and in-house developers and end users at highly regulated companies.
3. Part of our brand. Our style and message must be consistent over the long term. Therefore, all of our content, irrespective of purpose or subject-matter, must pull the reader in the same direction and reinforce our key messages.
4. High quality. Quality in writing reflects the professionalism of our organization. We pay attention to the rules of grammar and spelling.
5. Clear & transparent. We aim to communicate simply, using language that is familiar to our audiences. People don’t buy what they don’t understand!
6. International. Mattermost has customers around the world and in many cases English is their second language. Use standard American English but do not use metaphors or expressions that people outside of North America are unlikely to understand.
7. Avoiding unintentional controversy. We might want to stir up a bit of controversy now and again – but only on relevant technological and business topics. Avoid subjects or analogies that might provoke an emotional or hostile response: religion, politics, warfare, personal relationships etc.
8. Fit for purpose. Is your content designed to persuade (e.g. an opinion piece), promote (e.g. a product description) or instruct (e.g. to guide a user through procedural steps)? Adjust your tone and your language accordingly.

Clear? So now let’s look at our 12 tips for brilliant writing. To win the reader’s attention, and hold it, our content must be a pleasure to read. Our words must sparkle. Yet at the same time, it should all seem effortless; it can be a turnoff if it appears that the writer is trying too hard.

These guidelines are in place to help you achieve the right balance.

Remember, these are only guidelines, not hard and fast rules that you have to follow slavishly. So, for example, you might decide that in a specific context the passive voice is better than the active (see Point 7).

In general, if something sounds right the day after you wrote it, it is right. We’d like you to bear our tips in mind, but we also want you to trust your own judgment.

Guidelines: 12 tips for sparkling content¶

1. Have something to say. Always ask yourself, what am I trying to communicate? When you have nothing of value to say, you will end up writing sentences that may sound meaningful but deliver nothing.
2. Think from the reader’s perspective. Then ask yourself, “What’s in it for me [the reader]?” For example, you might be proud to announce an exciting new product feature, but unless you can quickly and concisely describe the benefit to the reader, the reader will lose interest. However, do not go to the other extreme and overstate benefits. That will also drive away the reader.
3. Be specific. Use concrete examples. Don’t take things for granted. Explain terms that the reader may be unfamiliar with. For example, do not write “data sovereignty” without explaining the term (e.g. “data sovereignty means the ability to control the country in which your data is stored and the laws under which it may be legally accessed”).
4. Choose simple words. Write use rather than utilize or leverage, help rather than facilitate, improve rather than ameliorate, imperfect rather than sub-optimal. It is true that in technical and business writing you sometimes need to choose words that are not in everyday usage, in order to communicate with precision and clarity. An example is the word “compliance”. However, if you use long or technical words unnecessarily, inappropriately or out of context you will only cloud your meaning. You would not, for example, say something like “my driving is fully in compliance with current traffic regulations”. Instead, you’d use an everyday term like “I observe the rules of the road”.
5. Write short sentences. Ideally, each sentence should contain one thought. More than one creates complexity and causes confusion. Reread each sentence and remove words that are unnecessary. These include “fluff” words like very, little and rather. If something is important, there is no need to add the word “very”.
6. Write short paragraphs. In academic writing, each paragraph develops one idea and often includes many sentences. But in casual, everyday writing, the style is less formal and paragraphs may be as short as a single sentence (or even a single word). Look at newspaper articles: journalists write short sentences because this makes information easy to digest.
7. Use the active voice. As a simple example: Mattermost improves your workplace productivity sounds far better than Your workplace productivity is improved by Mattermost. The active voice is direct and concrete. The passive voice tends to lead you into obscure and abstract thinking.
8. Don’t ramble or overwrite. Remind yourself what you set out to communicate (Point 1). Do not lose your focus. Keep the text as long as necessary, but as short as possible.
9. Avoid cliché openers. By that we mean opening sentences that the audience has read a million times before, such as, “In an increasingly competitive business environment…”
10. Edit ruthlessly. Use the first draft to get your thoughts together. Then leave it for a few hours (or even days). Shorten, delete, and rewrite anything that does not add to the meaning. Run a spelling and grammar check.
11. Ask a colleague. Still not 100% happy? A colleague should review the text and tell you if anything is unclear or if you could express yourself better. They might offer some useful fresh insights.
12. Now, relax. If you are in the wrong frame of mind you will either get writer’s block or your writing will be stiff and unnatural. Take your time. Remove any distractions. Keep things simple.