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:
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.
.. [] 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.
Last updated
