Style guide

source/guides/core.rst

@@ -14,8 +14,18 @@ Development Process
    /process/release-process*
    /process/accepting-pull-request*
    /process/community-systems*
-   /process/documentation-guidelines*
+   /process/documentation-guidelines.md
 
+Documentation Style Guide
+=========================
+
+.. toctree::
+   :maxdepth: 3
+
+   Introduction </process/sg_mattermost-doc-style.rst>
+   /process/sg_document-structure.rst
+   /process/sg_grammar-spelling-mechanics.rst
+   /process/sg_rest_markup.rst
 
 Joining the Team 
 =========================
@@ -29,4 +39,3 @@ Joining the Team
    /process/security*
    /process/training*
    /process/people-ops*
-

source/process/documentation-guidelines.md

@@ -1,5 +1,9 @@
 # Documentation Conventions
 
+**Note:** This document is in the process of being revised. See the new work-in-progress version here: <a href="sg_mattermost-doc-style.html">Mattermost Documentation Style Guide</a>.
+
+----
+
 The most important thing about documentation is getting it done and out to the community. 
 
 After that, we can work on upgrading the quality of documentation. The below chart summarizes the different levels of documentation and how the quality gates are applied. 

source/process/sg_document-structure.rst

@@ -0,0 +1,30 @@
+==================
+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 :ref:`capital`.
+
+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.

source/process/sg_grammar-spelling-mechanics.rst

@@ -0,0 +1,137 @@
+================================
+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.
+
+.. _capital:
+
+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
+=======
+
+Use decimal numbers except when the number is the first word of a sentence. 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
+=================
+
+==============  =========================================
+Text            Highlight
+==============  =========================================
+filepath        monospace (directory paths, file names)
+inline code     monospace
+code block      monospace
+Menu selection  bold
+UI selection    bold (includes buttons, links, names of controls, and field names)
+text entry      monospace
+references      italic
+==============  =========================================
+
+Contractions
+============
+
+As a general rule, contractions are acceptable in Mattermost documents.
+
+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.
+
+  a. This is a substep.
+  b. This is another substep.
+
+3. This is the third step.

source/process/sg_mattermost-doc-style.rst

@@ -0,0 +1,28 @@
+====================================
+Mattermost Documentation Style Guide
+====================================
+
+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.
+
+.. comments
+
+  Main screen, Navigation panel, Message Details panel
+
+  how to link to other documents. ie, not click here
+
+  should be no need for section breaks, ie ---------- that gets output as <br>
+
+  avoid documenting features; instead, document tasks. describe things that people want to do
+
+  Steps: Each step should describe one action. Each step should be a complete sentence.
+
+  avoid noun clusters. that is, three or more nouns in a row
+
+  Use might or can instead of may. use 'may' only when giving permission. 
+
+  Users sign in to Mattermost; they do not log in.

source/process/sg_rest_markup.rst

@@ -0,0 +1,128 @@
+=============================
+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 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 an overline and an underline. Use the = character. For example:
+
+::
+
+  =============================
+  Using reStructuredText Markup
+  =============================
+
+Unlike Markdown, overlines and 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
+  ``````````````
+
+Bullet lists
+============
+
+For bullet lists and sublists, use only the - character. For example:
+
+.. code-block:: none
+
+  - 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:
+
+.. code-block:: none
+
+  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.
+
+Linking to other documents
+==========================
+
+Use relative links to reference other documents in the Mattermost doc set. Also, use either the :doc: or :ref: linking mechanisms that are provided by Sphinx.
+
+Preferred
+  .. code-block:: none
+
+    :doc:`sg_mattermost-doc-style`
+    :ref:`target-label`
+
+Avoid
+  .. code-block:: none
+
+    `Mattermost Documentation Style Guide`_
+
+    _Mattermost Documentation Style Guide: sg_mattermost-doc-style.html
+
+For more information about how to use :doc: and :ref:, see `Inline markup`_ on the Sphinx documentation page.
+
+
+.. _reStructuredText Markup Specification: http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html
+.. _Sphinx Markup Constructs: http://www.sphinx-doc.org/en/stable/markup/index.html
+.. _Inline markup: http://www.sphinx-doc.org/en/stable/markup/inline.html
+
+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.
+
+To use a literal block as originally intended in the reStructuredText specification, you must cheat a little, and use explicit code block markup with the language set to `none`. For example:
+
+.. code-block:: none
+
+  .. code-block:: none
+
+
+Menu selections
+===============
+
+To indicate a series of menu selections, avoud the menuselection role that the Sphinx processor provides.
+
+Preferred
+  .. code-block:: none
+
+    Click **File > Open**.
+
+  This produces Click **File > Open**.
+
+Avoid
+  .. code-block:: none
+
+    Click :menuselection:`File --> Open`.
+
+  This produces :menuselection:`File --> Open`