Documentation Guidelines

This is the Mattermost style guide for documentation. It acts as a reference for writers and editors to ensure that the Mattermost documentation is consistent and clear.

Note

The style guide is not intended to slow down or otherwise impede contributions, which are always welcome. No contribution will be rejected due to non-conforming style, although it might be edited.

General Guidelines

The Mattermost documentation must be of high quality. It must be accurate and clear, and be presented with a style and tone that is appropriate for technical content.

Style Guide Applicability

The style guide applies to all end-user, developer, and administrator documentation that appears on the Mattermost documentation site at https://docs.mattermost.com.

Apply the style guide in the following situations:

  • when you create a new document
  • when you convert a document from Markdown to reStructuredText
  • when you revise a document

When you revise a document, apply the style guide rules to the part that you changed. If you have time to update the rest of the document, then do so. If the scope is significantly greater than you originally anticipated, then do what you can and what makes sense, and then create an issue in GitHub. Give the issue an appropriate title, such as File XXX converted to .rst, but needs updating for style guide.

Write in the Context of Achievement

The documentation should help Mattermost users and administrators achieve their goals. Write imperative sentences as much as possible. Imperative sentences begin with verbs and give instructions, information, and advice to help people install, administer, and use Mattermost with success.

Use positive constructs as much as possible, but note that a negative construct can act as a warning that causes a reader to pay closer attention to the content, resulting in higher levels of accomplishment.

Write to Facilitate Scanning

Readers need to find information quickly. People don’t read documentation as much as they scan it for solutions to their immediate problem. Writing and presentation styles that seem redundant in essays or other texts are often helpful to people scanning for information.

Use Headings, Lists, and Emphasis

Format text to give a visual hierarchy that allows readers to see the overall content of the page by scanning it. Use headings, lists, and emphasis to signal importance. Headings should summarize the topic of the underlying information so that when readers scan a page, they can get an accurate picture of the contents.

Be clear
Write short, active sentences using everyday vocabulary. Maintain a visual separation between page elements.
Be concise
Minimize content so it can be found and remembered. Keep pages short, modular, and focused on a single topic.
Be consistent
Refer to one thing or idea with the same word throughout the page.

Write for an International Audience

Mattermost documentation is translated into several languages for use in many countries and cultures. For this reason, you must consider cultural differences on a global scale. Names, places, events, and actions should be chosen as carefully as possible to avoid misunderstanding.

Also remember that English is not the primary language of many readers of the documentation. Keep the following advice in mind when writing:

  • Choose words with one or very few meanings.
  • Use simple verb forms in writing. Most verbs in the simple form are likely to have an equivalent in another language.
  • Avoid jargon and slang words.
  • Limit difficult words to technical terms where their use is unavoidable.
  • Always make sure that your spelling is correct.

Word Usage Guidelines

To promote consistency and clarity, follow the word usage and spelling guidelines in the following list.

can, might, may
The word may can have several meanings. To avoid ambiguity, use can or might instead of may. Use can to mean capable of and might to mean that something is possible. Use may only to give permission to do something.
downtime
Use as one word downtime, not down time.
emoji, emojis
Use emojis as the plural form of emoji.
login, log in, log into
Use login as a noun or adjective, and log in and log into as verbs. For example: Log into the Mattermost server using your System Admin login credentials.
setup, set up
Use setup as a noun or adjective, and set up as a verb. For example: Set up your operating system as described in the Ubuntu documentation.
sign-in, sign in, and sign into
Use sign-in as a noun or adjective, and sign in and sign into as verbs. For example: Sign into your Mattermost account using the sign-in credentials that were sent to you.
single sign-on
Single sign-on is abbreviated as SSO. When using the long form in a heading with title case, it’s Single Sign-on.

Gender-neutral Text

Avoid constructs where you are forced to write either he or she or his or her. You can use they or their as singular forms instead.

Preferred
The community manager monitors the forum for well-written questions and answers, and posts them to the Contributors channel.
Avoid
The community manager posts questions and answers that they think are well-written.
Do not use
The community manager posts questions and answers that he or she thinks are well-written.

Document Structure

Structure and organization are an important part of a document’s ease of use and its understandability. Information should be organized and presented in a logical order, with similar subjects grouped together in the same section.

In most cases, a document has a title, an introductory paragraph, and one or more sections.

Try to keep only one topic in a page. Shorter topics are easier to reuse in other documents, are easier to write and edit, and are easier to translate.

Document Title

Use a title that accurately reflects the content of the document. People scan the table of contents looking for answers; it’s often faster than using the built-in search engine.

Use title case for document titles. For more information and an example of capitalization, see Capitalization.

Introductory Paragraph

Each page should have an introduction that acts as a short description of the document. The short description should be a single paragraph of no more than three sentences. Keep in mind that the description is displayed in the search results along with the page title. People read the description to help them decide if the document is the one that they want.

Table of Contents

If the document contains more than four sections or subsections, add a table of contents to help the user navigate the document, see Table of Contents.

Document Sections

To make pages easier for people to quickly scan for the content that they’re looking for, break your document up into logical sections. Each section should have a title, and the title should relate to the content of the section. Use title case for the section title.

A section title is not required if you have only one section.

Grammar, Spelling, and Mechanics

To maintain consistency across all Mattermost technical documentation, adhere to the guidelines here.

Language and Spelling

Write documents in English. Use American spelling.

Paragraphs and Sentences

Paragraphs should express one idea or topic. Long paragraphs are sometimes difficult to read on screen, so try to keep them to five sentences or less. Short paragraphs are easier for people to scan quickly.

Try to keep sentences to 25 words or less in length. Short, single-clause sentences are often easier to understand and easier to translate. Tools such as the Hemingway writing app can be helpful in evaluating readability. Target a readability level of Grade 6.

Tone

Use a direct, impartial tone. Mattermost documentation is written to answer questions and solve problems, not to entertain.

Preferred
If login fails due to an invalid password, turn Caps Lock off and then re-enter your password.
Avoid
Failed sign in? No problem! Simply enter the correct password and we’ll let you in right away.

Voice

Use active voice in preference to passive voice. Active voice has the subject of a sentence doing the action. In passive voice, the subject has an action done to it.

Preferred
The system opens the Status pane.
Avoid
The Status pane will be opened by the system.

Person

Use the second person and avoid the first person.

Preferred
View the status in the Status pane.
Avoid
We’ll view the status in the Status pane.

Tense

Use the present tense.

Preferred
Sharing this link lets other users view the linked message.
Avoid
Sharing this link will let other users view the linked message.

Commas

Use the serial comma unless doing so decreases clarity and understanding of the sentence.

Preferred
The cows ran from wolves, coyotes, and mosquitoes.
Avoid
The cows ran from wolves, coyotes and mosquitoes.

Capitalization

Use title case for page titles and section titles.

Title case
Grammar, Spelling, and Mechanics
Sentence case
Language and spelling

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.

Preferred
Three cows ran for six kilometers when they saw 2,300,097 mosquitoes chasing them.
Avoid
3 cows ran for 6 kilometers when they saw 2300097 mosquitoes chasing them.

Text Formatting

Use highlighting of text to visually set off words and phrases that are important to readers. Content that should be highlighted includes file names, UI controls, and window titles. The following table has a comprehensive list with examples.

Text Format Example
Code samples monospace See Code Blocks with Syntax Highlighting for an example.
Commands monospace “At the command line, type sudo apt-get install nginx.”
Directory name monospace /opt/mattermost
File name monospace config.py
Inline code monospace fmt.Printf("2 times %d = %d\n", x, y )
Keystrokes monospace “Type https:// in the string field.”
Screen output monospace See Literal Blocks for an example.
Parameter values monospace “Set the auto-config parameter to false
Field names bold “Enter the font in the Display Font field.”
Clickable control bold “Click File > Save.”
Citations italic “Read the book Clean Code by Robert Martin.”
Window titles italic “The Account Settings window opens.”
User account names italic “Log in to the mysql account.”
Parameter names italic “Set the auto-config parameter to false
Keyboard buttons Key1+Key2 “Press CTRL+U to upload a file.”
Placeholder field {placeholder} “Use the URL in the form of {hostname}.mattermost.com/{team}.”

Bullet Lists

The list items in a bullet list can be either all complete sentences or all sentence fragments. Don’t mix complete sentences and sentence fragments in a single list. Remember that a complete sentence begins with an upper case letter and ends with a punctuation mark.

Numbered Lists and Procedures

Create numbered lists and procedure steps using arabic numerals for the top-level list and lower case alpha characters for the first nested list. For example:

  1. This is the first step.
  2. This is the second step.
  1. This is a substep.
  2. This is another substep.
  1. This is the third step.

Name-value Groups

Use a name-value group instead of a hand-created list.

A name-value group is typically a group of terms and their corresponding definitions, but can also be questions and answers, topics and values, or other name-value groups. In HTML output, a name-value group is represented as a definition list.

Preferred
Total Users
The total number of active accounts created on your system. Excludes inactive accounts.
Total Teams
The total number of teams created on your system.
Avoid

Total Users: The total number of active accounts created on your system. Excludes inactive accounts.

Total Teams: The total number of teams created on your system.

Document Linking

When creating a link to another document in the Mattermost documentation, create a link with a relative URL. To create relative links in reStructuredText, see Internal Links to Mattermost Docs.

A link with an absolute URL is not as flexible as a relative URL. Relative URLs don’t break when the documentation is moved to another host, or if the documentation is hosted on a server that’s behind a firewall without access to the Internet.

ReStructuredText Markup

The reStructuredText specification allows for a certain degree of flexibility in markup to achieve your goals. For example, you can use any one of more than a dozen characters for section title underlines, and you have the option of using an overline in addition to an underline.

However, for consistency and ease of use, the Mattermost documentation should use a single convention, despite the existence of allowable alternatives.

For more information about reStructuredText markup, see the reStructuredText Markup Specification. Additional markup constructs are implemented by Sphinx, the documentation generator used by Mattermost. For information about the additional constructs, see Sphinx Markup Constructs.

Use the following markup conventions in Mattermost documentation:

Page Titles

Underline page titles using =, with no overline. Underlines should be as long as the title text. For example:

Document Title
==============

Section Titles

Underline using - for section titles. For example:

Section Title
-------------

Underline subsections using ~ for the first subsection level, and ^ for the second subsection level. For example:

Subsection One
~~~~~~~~~~~~~~

Subsection Two
^^^^^^^^^^^^^^

Table of Contents

Insert a table of contents into a document using the following format:

.. contents::
    :backlinks: top

Inline Markup

Bold
Use double asterisks. For example: **bold text**.
Italic
Use single asterisk. For example: *italic text*.
Monospace
Use double backquotes. For example: ``monospace text``

Bullet Lists

For bullet lists and sublists, use - before the list item. For example:

- list item one
- list item two
  - sublist item one
  - sublist item two
- list item three

Numbered Lists and Procedure Steps

Create numbered lists and procedure steps using numbers for the top-level list and lower case alpha characters for the first nested list. For example:

1. This is item one.
2. This is item two.

  a. This is nested item one.
  b. This is nested item two.

3. This is item three.

Name-value Groups

To create a name-value group such as a definition list, type the term on a line by itself. On the next line, indent the definition. For example:

Total Users
  The total number of active accounts created on your system. Excludes inactive accounts.
Total Teams
  The total number of teams created on your system.

Images

Use the following construct to insert an image:

.. image:: ../images/choices.png

You should use alt tag for all images.

You can also add the following image options: height, width, scale, align, and target. For example:

.. image:: ../images/choices.png
  :alt: The choices that you can make.
  :height: 100px //number refers to pixels
  :width: 200px //number refers to pixels
  :align: left //left, right or middle
  :scale: 50 //number is a percentage

Inserting an inline image is a bit more complicated. It’s a two-part construct that consists of a label and the image directive. Surround the label text with vertical bars, the | character. For example:

Some of the emoji that you can use are |emoji|.

Then insert the following image directive at the bottom of the document:

.. |emoji| image:: ../images/emoji.png
  :alt: Some of the emoji that you can use.
  :align: middle

Literal Blocks

To use a literal block with no syntax highlighting, use the Sphinx code-block directive with the language set to none. For example:

.. code-block:: none

Code Blocks with Syntax Highlighting

To create a code block with syntax highlighting, use the Sphinx code-block directive with the language set to the language that you want highlighted. Many languages are available, but in Mattermost documentation the most likely ones are as follows:

  • go
  • rest
  • html
  • javascript
  • coffee
  • bash

The following example is a block of Go code using the :linenos: option, which causes line numbers to be displayed.

.. code-block:: go
  :linenos:

  newPassword := props["new_password"]
      if err := utils.IsPasswordValid(newPassword); err != nil {
              c.Err = err
              return
      }

The example produces the following output:

1
2
3
4
5
newPassword := props["new_password"]
      if err := utils.IsPasswordValid(newPassword); err != nil {
              c.Err = err
              return
      }