Mattermost Handbook
Need help?How to spend company moneyHow to update the HandbookRelease overview
0.2.1
0.2.1
  • Mattermost Handbook
  • Company
    • About Mattermost
      • List of terms
      • Business model
      • Mindsets
    • "How to" guides for staff
      • How to set up a 1-1 channel
      • How to update the handbook
      • How to manage Handbook notifications
      • How to change mobile device
        • How to handle a lost mobile device
      • How to do a mini-retrospective
      • How to autolink keywords in Mattermost
  • Operations
    • Company operations
      • Areas of Responsibility
      • Mattermost Leadership Team (MLT)
        • MLT cadence
      • Company measures
        • Metrics definitions
        • FY23 goals board
        • MLT metrics
      • Company cadence
      • Company policies
        • Community response policy
        • Security policy
      • Company processes
        • Issue/solution process
        • Company agreements
        • Publishing
          • Public web properties
          • Publishing guidelines
            • Brand and visual design guidelines
            • Voice, tone, and writing style guidelines
              • Contribute to documentation
            • Confidentiality guidelines
          • Post-publication quality control process
      • Handbook processes and policies
        • Handbook onboarding
      • Fiscal year planning
    • Research and Development
      • Organization
        • Tech Writing
        • Data engineering
        • Delivery
        • Cloud Platform
        • Site Reliability Engineering
        • GRC
        • Product Security
        • Security Operations
      • Processes
        • Feature Labels
      • Product
        • Product planning
          • Product philosophy and principles
          • Prioritization process
          • Release planning process
          • Roadmap views
          • Release plan
          • Launch plan
          • Feature requests
        • Development process
          • Mobile feature guidelines
          • Deprecation policy
          • Mattermost software requirements process
          • Jira ticket lifecycle
          • Creating new Jira bug tickets
            • Priority levels for tickets
            • Jira fix versions
        • Release process
          • Release overview
          • Feature release process
          • Dot release process
          • Security release process
          • Mobile app release process
          • Desktop app release process
          • Release tips
          • Release scorecard definitions
        • How-to guides for Product
          • How to use productboard
          • How to record a roadmap video
          • How to update integrations directory
          • How to write a feature release announcement
        • Product Management team handbook
          • Product Management Areas of Ownership
          • Product Manager onboarding
          • Product Manager levels
          • Professional development
        • Product Design team handbook
          • Product Design levels
        • Technical Writing team handbook
          • Work with us
          • User interface text guidelines
          • Documentation style guide
          • Our terminology
          • Guidelines for PMs and developers
          • Guidelines for community contributions
          • Technical Writer levels
          • Docathon 2021
            • Getting started with contributing
        • Growth
          • A/B testing methodology
          • PQL definition
        • Analytics
          • Product Analyst Engineer levels
          • Looker
            • Dashboards
            • Explores
          • Telemetry
        • Developer relations
        • Product team hangouts
      • Engineering
        • Infrastructure engineering
          • Cloud infrastructure cost KPIs
          • Cloud data export process
          • Cloud churn process
          • Reliability Manifesto
          • Production Readiness Review
          • Infrastructure Library
        • Integrations team processes
        • Plugin release process
        • Data Engineering
        • Sustained Engineering
          • On call
        • How to go to a conference
        • Public speaking
        • Core contributor expanded access policy
      • Quality Assurance
        • QA workflow
        • QA testing tips and tools
        • Rainforest process
    • Messaging and Math
      • How-to guides for M&M
        • How to create release announcements
        • How to create screenshots and GIFs
        • How to write Mattermost case studies
        • How to write guest blog posts for Mattermost apps and services
        • How to write Mattermost recipes
        • How to compose tweets
        • How to create a split test for web page
        • How to run meetups
        • How to run executive dinners
      • Checklists for M&M
        • Blog post checklist
        • Bio checklist
      • Mattermost websites
      • Demand generation reporting
      • M&M Asana guidelines
      • Content marketing
        • How to use the editorial calendar
        • Content development and distribution
        • Video content guidelines
        • How to contribute content
    • Sales
      • Deal Desk
      • Partner programs
      • Lead management
    • Deployment Engineering
      • Overview
      • Workflows
      • Frequently Asked Questions
      • Playbook for MME Sev 1 Outages
      • Status Update Template
    • Program Management
    • Customer Success
      • Customer Support
    • Legal
      • Contracts
      • Ironclad Basics
        • Company-Wide Workflows
        • Sales Contracts and Workflows
        • Signing a Contract and Contract Repository
    • Finance
      • Budget
      • How to use Airbase
        • Access Airbase
        • Navigate Airbase
        • How to submit a purchase request
        • How to submit a reimbursement request
        • How to review a reimbursement request
        • Vendor portal guide
        • Frequently asked questions
      • Onboarding
        • Vendor onboarding
        • ROW staff onboarding
      • Staff member expenses
        • How to spend company money
        • How to spend company money: Internships
        • Corporate credit card policy
        • How to access Airbase
        • Gifting policy
        • How to book airfare and travel
        • How to reimburse the company
        • How to convert currencies
        • How to get paid
      • Arrange a Bounty Program
      • Naming files and agreements
      • Risk management
        • Mattermost U.S. consulting agreements
      • Operations playbook
    • Security
      • Policies
      • Privacy
        • Data deletion requests
        • Data subject access requests
      • Product Security
        • Product Vulnerability Process
        • Working on security-sensitive pull requests
        • Secure Software Development guide
      • Security Operations
        • User guides
    • Workplace
      • PeopleOps
        • HR cadences
        • HR systems
        • HR Processes
        • Working at Mattermost
          • Onboarding
            • Things everyone must know
            • Staff onboarding
            • Engineer onboarding timeline and expectations
            • Manager onboarding
            • Frequently asked questions
          • Learning and development
          • Mattermost communication best practices
          • Paid time off
            • Out of office email example
          • Travel
            • Business travel insurance
          • Leaves of absence
            • Pregnancy leave
            • Baby bonding parental leave
            • Jury duty
          • Workplace program
          • Relocation
          • Total rewards
        • Performance reviews
          • Formal review process
          • New staff performance review
          • Informal review process
        • Transfers and promotions
        • Offboarding instructions for managers
        • People compliance
      • People policies
      • Groups
        • Staff Resource Groups
      • Approvals and iteration
      • IT
        • IT helpdesk
        • Hardware and software purchases
        • Hardware buy back policy
        • Software systems
  • Contributors
    • Contributors
      • Equity, diversity, and inclusion
      • How to contribute to Mattermost
        • Community Content program
        • Documentation contributions
        • Help Wanted tickets
        • Localization
        • Contribution events
      • Mattermost community
      • Contributor kindness
      • Community systems
      • Guidelines and playbooks
        • Social engagement guidelines
        • Contribution guidelines and code of conduct
        • Mattermost Community playbook
        • How to run a Hackathon
        • Hacktoberfest event organizer guide for Mattermost
    • MatterCon
      • Staff information privacy management
      • Mattermost events code of conduct
      • MatterCon2021
    • Join us
      • Ice-breakers
      • Help Wanted tickets
      • Localization
      • Mattermost GitHub sponsorship
      • Things candidates should know
      • Staff recruiting
      • Recruiting cadences
        • Product Manager hiring process
      • Exec recruiting
        • EA logistics
  • Help and support
    • Contact us
Powered by GitBook
On this page
  • Types of in-product content
  • Writing for inclusion and diversity
  • Accessibility
  • Messaging guidelines
  • System messages
  • Notification messages
  • Confirmation messages
  • Warning messages
  • Error messages
  • In-product copy
  • How we make in-product text changes
  • How we write things (WIP)
  • Guidelines for UI punctuation
  • Guidelines for capitalization
  • Terminology
  • Button labels and links
  • Navigation labels
  • Input labels
  • Guidelines for UI elements

Was this helpful?

Edit on Git
Export as PDF
  1. Operations
  2. Research and Development
  3. Product
  4. Technical Writing team handbook

User interface text guidelines

Mattermost user interface content (microcopy) is where we can set our users up for success and build engagement with the product instead of reliance on documentation.

When we write copy for our product messaging our primary goals are to:

  • Write with empathy

  • Provide context

  • Help users build mental models

  • Reduce cognitive load

  • Proactively prevent failure

To achieve these goals, we ensure that we have the right content for the right user at the right time. In addition to this, we prioritize:

  • Plain language: We choose natural language, simple words, and short sentences for documentation and in-product text.

  • Readability: We strive to make our documentation pages easy to scan and not overwhelming.

  • Consistency: We ensure that we all refer to the same things using the same words or names, to avoid confusion.

These writing principles mean that we think like a friend, and talk like a coach to reduce friction and increase satisfaction.

  • Keep in mind that your users are from all over the world.

  • Use the present tense to describe a current state or condition, and the future tense to state something that is very definitely going to happen.

  • Use the active voice, except for these cases:

    • If you’ll end up blaming the user. For example, don’t say You entered an incorrect password. Instead, say The password is incorrect.

    • If you’re describing what just happened. For example: Your incoming webhook is set up.

    • If the subject (the doer of an action) is the Mattermost application itself. For example: The image has been deleted instead of The server deleted the image.

  • If you’re asking the user to do or not do something, use imperatives (command phrases). For example, use Don't change the Hostname instead of It's not recommended to change the Hostname. Better still, explain what could go wrong if they do or don’t do something. For example: Don't change the Hostname because doing so will break something.

Types of in-product content

In general, users will encounter the following types of messaging when using Mattermost:

  • Help, hints, or informative text

  • Calls to action

  • Confirmation dialogs

  • Errors

  • Notifications

In general, this content is either:

  • Static text on the user interface

  • An actionable button which leads to a process

  • Triggered because something happened

Writing for inclusion and diversity

Accessibility

This section is being built out. In the meantime, here are some of the things we take into account when writing content:

  • Colors used on-screen

  • Plain and clear language

Messaging guidelines

Don’t blame the user. Inform them about what happened, explain why it happened, and suggest a way forward. Try to use complete sentences in your messages. A sentence phrase (an incomplete sentence) might make sense in English but could present internationalization challenges.

System messages

System messages can be one of the following types: notification, confirmation, warning, and error. The following sections contain guidelines that are specific to each of these types.

If a system message contains variables (tokens):

  • Don't use verbs or adjectives as variables.

  • Don't create plurals of variables by adding an "s".

  • If the variable is a noun, use a qualifier after the variable. For example, say The {channel_name} channel was created rather than The {channel_name} was created.

Notification messages

A notification message informs the user about an event or action that took place. These messages don't need any user input, and don't prevent the user from continuing to use Mattermost.

  • Use either a complete sentence or a sentence phrase.

  • If using a complete sentence, end it with a period.

  • Examples:

    • Member added to channel.

    • The plugin was installed.

Confirmation messages

A confirmation message requires user input to confirm that they want to proceed with the action. Confirmation must be provided (either to continue or cancel) before the user can continue to use Mattermost.

  • Use complete sentences.

  • Include a question that has a Yes/No answer.

  • Examples:

    • Are you sure you want to delete this channel?

    • A plugin with this ID already exists. Would you like to overwrite it?

Warning messages

A warning message alerts the user that something that might go wrong. They can continue using Mattermost unless the warning message needs user input.

  • Use complete sentences.

  • Explain what has happened, or can happen, and what may go wrong as a result.

  • Examples:

    • The Enterprise license expires in 2 days. If it's not renewed, some features will be disabled on license expiry.

    • If you claim this AD/LDAP account, you won't be able to log in with your email address.

Error messages

An error message informs the user that something went wrong. Errors prevent the user from completing a task or accessing a feature until the error is resolved.

  • Use complete sentences.

  • If what went wrong isn’t obvious, explain in one sentence.

  • If a solution or workaround isn’t obvious, suggest one.

  • Examples:

    • Messages must have fewer than 120 characters.

    • A connection to the Marketplace server could not be established. Check your settings in the System Console.

In-product copy

How we make in-product text changes

Making an in-product text change starts with identifying which repository, and where in the product code, a change is needed. Many in-product strings live in the mattermost/webapp/i18n/en.json or mattermost/server/i18n/en.json English translation files. However, some strings may additionally live within product code too. You may need to update both .json and .tsx files. QA can help apply updates to impacted SNAP or E2E files.

If TSX files are impacted by an in-product change, run the command npm run updatesnapshot ./directory-or-file to capture any TXS changes within the en.json file. Run this command against multiple files by separating files with spaces: npm run updatesnapshot -i ./path_to_test.txt_file ./path_to_test.txt_file ./path_to_test.txt_file

If E2E tests are failing during PR reviews, reach out for assistance from either the team who initiated the feature or the SDET, QA team. Then, add the QA Needed label for all in-product text change PRs. If you know the QA team member based on the affected product area, add them as a QA reviewer, otherwise mention the QA Lead in the PR notes.

How we write things (WIP)

We write with empathy in the context of achievement using natural language. This can be quite hard to do; as technical writers we generally lean toward very clear and concise writing that can feel clinical. Writing more naturally means we try to avoid convoluted phrasing and we try to make things more simple.

So, instead of saying: "When testing the Java app ensure your third-party connection is secure before initiating the test sequence." rather say: "Make sure your third-party connection is secure before testing the app."

Because we strive to use natural language, the way we phrase microcopy isn't templated - that would defeat the point. Instead, here are some examples of microcopy we use for various features and products. The common theme is clarity and empathy.

Which words to use

There's a big difference between "jargon" and "terminology".

Jargon is usually industry-specific and can be isolating or confusing for users who aren't deeply familiar with them. Terminology is usually universally-accepted and generally understood.

Guidelines for UI punctuation

Headings

These are H1 headings such as the title of a modal. Titles shouldn't have periods unless the headline is more than one sentence. Titles also shouldn't contain punctuation such as question marks, colons, semi-colons.

Paragraphs

Paragraphs should always be properly punctuated.

Sentences

When you're writing descriptive UI copy, try to write full sentences which can be punctuated. If the copy you're writing can be expressed in a single word, consider moving that word to the input field instead.

Bullets

Bullet lists shouldn't have periods unless the bullet text is more than one sentence.

Button labels

Button labels shouldn't have periods or other punctuation.

Guidelines for capitalization

We follow the same capitalization rules across all our documentation assets, including in-product text and UI elements: Always use sentence case (except where you're using a proper noun, of course). This applies to:

  • Page titles

  • Page headings

  • Section headings

  • Button labels

  • Input labels

  • Navigation labels

  • Menu items

  • Field hint text

  • Hover text

Here's an example of an incorrect heading: This Article is About Mattermost. The correct version is: This article is about Mattermost.

Terminology

Button labels and links

Button labels should always use action words and describe the action as concisely as possible. They should be limited to four words or less. Examples: “Log in”, “Send invitation”.

Navigation labels

Navigation labels should be as short as possible and support the user in finding their way.

Input labels

Input labels should be as short and concise as possible and describe the input field.

Guidelines for UI elements

Use this table when writing the text for UI elements such as windows, dialog boxes, labels, and prompts.

Element
Image
Capitalization
Phrasing
Examples

Menu

Headline style

  • Noun, noun phrase, or verb

  • No punctuation

  • Not more than three words

  • Action after clicking is obvious, without needing someone to click to discover

  • Members

  • Account Preferences

  • Log Out

Tooltip

Sentence style

  • Sentence fragment or sentence

  • No punctuation

  • Include articles (a, an, the)

  • Keep it short

  • Start a Zoom meeting

  • Flag for following up

  • Remove from this list

In-field text

Sentence style

  • Sentence fragment, sentence, or word that's an example of a valid entry

  • No punctuation

  • Include articles (a, an, the)

  • Add a comment

  • Search

Action button

Headline style

  • Verb or verb phrase

  • No longer than three words

  • No articles (a, an, the)

  • Exceptions: OK, Yes, No

  • Add Comment

  • Edit

Label before a UI element

Sentence style

  • Noun, verb, or sentence fragment that's the title of the UI element

  • End with a colon where it precedes another UI element such as a radio button or check box

  • Include articles (a, an, the)

  • Sign in with:

  • Other words, separated by commas:

Label after a UI element

Sentence style

  • Noun, verb, or sentence fragment

  • No punctuation

  • Brief (longer explanations belong to help text)

  • Channels grouped by type

  • Alphabetically

Help text

Sentence style

Complete sentences, with punctuation

  • You can add 20 more people.

  • People are invited automatically to join the channel.

Title

Headline style

  • Sentence fragment or sentence

  • No punctuation

  • Notification Preferences for Channel

  • Contributors

.. [] For headline style, capitalize all words except those with three letters or fewer, articles (a, an_,_ the_), prepositions (on,_ to_,_ in_,_ from_,_ of_), and coordinating conjunctions (and,_ but_,_ or_,_ for*). Despite these exceptions, always capitalize the first and last word. For sentence case, capitalize only the first word.

PreviousWork with usNextDocumentation style guide

Last updated 2 years ago

Was this helpful?

This section is being built out. In the meantime, please consult for the type of guidelines we follow when writing with inclusion and diversity in mind.

If you have any questions about writing for inclusion and diversity, or notice something we can improve, please tell us! You can find us on Mattermost in the channel.

Take a look at for some more information on accessibility.

Have any ideas or feedback? You can find us on Mattermost in the channel.

The Technical Writers often work with the UI/UX team on in-product copy. The majority of guidelines are available in the .

While its possible to manage in-product text changes using GitHub web tools, writers may find it more straightforward to clone each of the main Mattermost repositories, including , , , and , and work through text changes in a local development environment instead.

Take a look at the for more information about how we approach casing.

One way of making life easier for our customers is to ensure we are consistent with our terminology. The technical writing team is continually working on improving our users' experience with our documentation and copy. You can read more about this work .

this page
DWG: Documentation Working Group
ALT tags
this article
DWG: Documentation Working Group
Mattermost Compass Design System
webapp
server
mobile
desktop
Google guide to capitalization
here