Voice, Tone and Writing Style Guidelines

Below is a start of voice, tone and writing style guidelines for public web properties. This is a work in progress, to be iterated on. Some of the content in this document is borrowed from the Mattermost Editorial Style Guide, which is managed by the Marketing team.

Some of the recommendations across the documents, such as punctuating lists and heading capitalization are not currently aligned but will be iterated on for alignment across all web properties.

Voice and tone

Our voice is informed by our foundation as a messaging platform for Enterprise Developers and DevOps, but respects that our client base spans many types of organizations. Writing is one way we can bring Mattermost’s values to life. And above all, our voice demonstrates our deep respect for our clients and users. Ultimately, Mattermost exists because of them, so it’s important we keep their needs at the forefront of our writing style.

Mattermost's voice is:

  • Clear

  • Concise

  • Consistent

  • Customer-centric

  • Professional

To achieve this, we keep the following principles in mind when writing content:

  • Use simple, plain language that is easy to understand and avoid jargon

  • Use direct, casual tone instead of an informal tone

  • Use the active voice

  • Write short, active sentences and maintain a visual separation between page elements

We generally avoid the following statements and phrases as they're overused and vague:

  • Work better

  • Do better work, faster

  • Get more done in less time

  • Chat (as a stand alone feature reference. However it is ok to use chat when describing a benefit "Create a Jira ticket without leaving your chat window" )

  • DevOps teams

  • Utilize (instead, use “use”)

  • High performance teams

  • Phrases that directly praise ourselves: “We’ve built an intuitive workplace messaging solution”, “It’s a joy to use”

The appropriate tone differs across different mediums. We don’t write help documentation with the same tone as website copy. You can vary your tone to fit the situation, just as you’d talk to an angry person with a different tone than with an excited child. Voice is to tone as climate is to weather.

The Mattermost voice remains the same, even when the tone varies.

Writing principles

  • Work on the premise that "Every page is page 1", as a large portion of users enters our documentation from a Google search

  • Add a summary to the top of each page for readers to be able to quickly assess the content for suitability

  • Write clearly and concisely - get to the point quickly without losing valuable information

  • Focus on what the target audience wants to accomplish by being practical/outcome-focused

  • Break long sections into smaller, easily digestable subpages

  • Have at most one key point or action per paragraph

  • Refer to one thing or idea with the same word throughout the page

  • Use ordered lists or bullets where appropriate, as they are generally easier to read than long blocks of text

  • Write for an international audience without idioms or expressions that people outside of your region are unlikely to understand

  • Minimize content so it can be found and remembered. Keep pages short, modular, and focused on a single topic

Writing style

Numbers

Spell out numbers when the number is the first word in a sentence or is less than or equal to ten, otherwise use numeric digits. Use commas to make long numbers easier to read.

Punctuation: Commas

We use the Oxford (serial) comma in our documentation. For example: "Mattermost's writing style is clear, concise, and simple" as opposed to "Mattermost's writing style is clear, concise and simple").

Capitalization

Use sentence case for page titles, headings, and section titles (e.g. "Writing guidelines for editors").

Visit our Style Guide for more information.

More Information

These guidelines were inspired by Stripe's knowledge base content and by other sites shared in this Document360 article.

Learn more about recommendations, analysis and next steps.