Merge pull request #642 from JeffSchering/style-guide

Style guide

source/guides/core.rst

@@ -17,6 +17,13 @@ Development Process
    /process/documentation-guidelines*
    /process/marketing-guidelines*
 
+Documentation Style Guide
+=========================
+
+.. toctree::
+   :maxdepth: 3
+
+   /process/sg_mattermost-doc-style.rst
 
 Joining the Team 
 =========================
@@ -30,4 +37,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,29 @@
+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,148 @@
+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
+-------
+
+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 :ref:`syntax-highlight` for an example.
+screen output   ``monospace``       See :ref:`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.
+
+  a. This is a substep.
+  b. This is another substep.
+
+3. 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 :ref:`relative-links-in-rst`.

source/process/sg_mattermost-doc-style.rst

@@ -0,0 +1,16 @@
+Introduction
+============
+
+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.
+
+.. contents::
+  :backlinks: top
+
+.. include:: sg_document-structure.rst
+.. include:: sg_grammar-spelling-mechanics.rst
+.. include:: sg_rest_markup.rst