Voice, tone, and writing style guidelines
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:
- Write clearly and concisely - get to the point quickly without losing valuable information
- Use simple, plain language that is easy to understand and family-friendly
- Avoid jargon and overly technical terminology
- 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
- Focus on what the target audience wants to accomplish by being practical/outcome-focused
- Write for an international audience without idioms or expressions that people outside of your country/region are unlikely to understand
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 technical and help documentation with the same tone as website copy or educational content. 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.
These guidelines were inspired by Stripe's knowledge base content and by other sites shared in this Document360 article.
Last modified 5mo ago