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.

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. People who use Mattermost rely on the documentation to get their jobs done. We don’t want to see an installation of Mattermost delayed because the documentation has an error or is difficult to understand.

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

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.

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

Avoid subsections. If you find that you need subsections, quite often the document is too long, or too complex, and needs to be broken up into several pages.

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

Commas

As a general rule, the serial comma results in greater clarity. However, there are always edge cases where a serial comma adds confusion to a sentence. Therefore, the Mattermost documentation will use the following rule for 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.

Tone

Use a direct, impartial tone. Most readers of the documentation are looking for answers and solutions to their problems; they are not looking for entertainment.

Preferred
If your password is rejected, check to make sure that Caps Lock is off, and then carefully type it in again.
Avoid
Failed sign in? No problem! Simply enter the correct password and we’ll let you in right away.

Capitalization

Use title case for page titles and sentence case for section titles.

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

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. Use passive voice only when you want to emphasize the action more than the subject.

Preferred
The system opens the Status pane.
Avoid
The Status pane is opened by the system.

Person

Use the second person and avoid the first person.

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

Numbers

Spell out numbers when they are the first word in a sentence, otherwise use numeric digits.

Use commas to make long numbers easier to read.

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

Text highlighting

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 Highlight Example
file name monospace config.py
directory name monospace /opt/mattermost
inline code monospace fmt.Printf("2 times %d = %d\n", x, y )
code samples monospace See Code blocks with syntax highlighting for an example.
screen output monospace See Literal blocks for an example.
menu selection bold “Click File > Save.”
UI selection bold “Click Next.”
field names bold “Enter the font in the Display Font field.”
commands monospace “At the command line, type sudo apt-get install nginx.”
citations italic “Read the book Clean Code by Robert Martin.”
window titles italic “The Account Settings window opens.”

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

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.

Linking to other documents

When creating a link to another document in the Mattermost documentation, create a link with a relative URL.

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.

To create relative links in reStructuredText, see Links to targets within the Mattermost docs.

Using 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

For page titles, use the = character for the title underline, with no overline. For example:

Using reStructuredText Markup
=============================

Unlike Markdown, underlines in reStructuredText must be at least as long as the title text.

Section titles

If your document has more than one section, use the - character for the section title underline. For example:

Section titles
--------------

If you do need subsections, use the the ^ character for the first subsection level, and the ` character for the second subsection level. For example:

Subsection One
^^^^^^^^^^^^^^

Subsection Two
``````````````

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 only the - character. 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 arabic numerals 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.

Images

Use the following construct to insert an image:

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

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

.. image:: ../images/choices.png
  :alt: The choices that you can make.
  :height: 100px
  :width: 200px
  :align: left

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

Later on in the document, perhaps at the end of the paragraph that contains the label, insert the following image directive:

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

Literal blocks

In reStructuredText markup, the double colon marks the start of a section of literal text that corresponds to the HTML <pre> tag. However, the Sphinx processor applies syntax highlighting for Python to literal blocks, which is not always desired in Mattermost documentation.

To use a literal block as originally intended in the reStructuredText specification, you must cheat a little, and 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
      }

The highlighting is provided by Pygments Python syntax highlighter, which supports a large number of programming and markup languages. For a complete list, see Available lexers