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

This section is being built out. In the meantime, please consult this page 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 DWG: Documentation Working Group channel.

Accessibility

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

• ALT tags

• Colors used on-screen

• Plain and clear language

Take a look at this article for some more information on accessibility.

Have any ideas or feedback? You can find us on Mattermost in the DWG: Documentation Working Group channel.

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

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

How we make in-product text changes

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 webapp, server, mobile, and desktop, and work through text changes in a local development environment instead.

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.

Take a look at the Google guide to capitalization for more information about how we approach casing.

Terminology

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 here.

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.