Mattermost Community Content Guidelines

The following guidelines are intended to help community members contribute guest blog posts or propose Twitter content, as well as for staff at Mattermost, Inc. interacting with the community.

How to write purposefully and persuasively

In this document we set out some easy-to-follow guidelines about writing. Follow them, while also relying on your own judgment. Writing for blogs, newsletters, magazine articles and other forms of content can then become a joy rather than a chore.

Before we get into the guidelines themselves, let’s consider the goal and objectives (why we think written communication is important in the first place) and a few principles (things to bear in mind when pursuing those goals).

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.

Guidelines for Twitter accounts

Composing Tweets:

  1. Avoid acronyms. Avoid acronyms when possible. For example, say “pull request” instead of “PR”, since only a subset of tweet readers are active GitHub users.
  2. Use the active voice. Avoid “has”, “was”, “have been” when possible. For example, instead of “Hackfest has started!” say “Hackfest starts now!”
  3. Include at most one link. To provide a clear call to action include at most one link per tweet, and place it near the end of the tweet.
  4. Use exclamation marks only for exciting announcements. An exclamation mark can be used when the announcement is exciting, but using an exclamation mark should be avoided when it can be confused with a signal for community to panic, e.g. “Security update released!”.
  5. Be welcoming. When asking someone to take action, use “Would you be open to” instead of “Would you like to”.

Guidelines for release announcements

Composing blog posts:

  1. Include [RELEASE] [HEADLINE] in title. Use titles that draw in IT audiences. E.g. “Mattermost 4.1: Integration enhancements with personal access tokens and streamlined apps, starting with JIRA”. Focus the title on 1 to 2 key features of the release.
  2. Use Twitter banners for images. Use Twitter banners to make visuals consistently high-quality throughout the release announcement. Also allows the marketing team use the images for tweets.
  3. Include a clear theme. Decide what theme to focus on throughout the release announcement. E.g. in 4.1 release announcement the focus was placed on integrations.
  4. Emphasize benefit. Always start each section with the benefit - the benefit should be clear in the first 1 or 2 sentences. IT audiences are typically more interested in the business benefits of technology than technical features. Emphasize benefit also in screenshots and image captions.
  5. Know your audience. Consider the audience you are writing this announcement for. E.g. admins who upgrade the Mattermost server, customers making a decision about purchasing the Enterprise Edition, end-users, or other.
  6. Test on mobile. Before you publish a blog post, make sure that it is mobile-friendly by testing it on smartphone and tablet platforms.