Implemented feedback and added some content

Author: JeffSchering

source/guides/core.rst

@@ -22,10 +22,7 @@ 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
+   /process/sg_mattermost-doc-style.rst
 
 Joining the Team 
 =========================

source/process/sg_document-structure.rst

@@ -9,19 +9,19 @@ In most cases, a document has a title, an introductory paragraph, and one or mor
 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.
 

source/process/sg_grammar-spelling-mechanics.rst

@@ -5,19 +5,19 @@ 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:
 
@@ -30,7 +30,7 @@ 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.
 
@@ -43,7 +43,7 @@ Avoid
 .. _capital:
 
 Capitalization
-==============
+--------------
 
 Use title case for page titles and sentence case for section titles.
 
@@ -54,7 +54,7 @@ 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.
 
@@ -65,7 +65,7 @@ Avoid
   The *Status* pane is opened by the system.
 
 Person
-======
+------
 
 Use the second person and avoid the first person.
 
@@ -76,9 +76,11 @@ 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.
+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.
@@ -87,27 +89,28 @@ 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.
+-----------------
+
+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.
 
@@ -118,12 +121,12 @@ 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:
 
@@ -135,3 +138,12 @@ Create numbered lists and procedure steps using arabic numerals for the top-leve
   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

@@ -1,6 +1,5 @@
-====================================
-Mattermost Documentation Style Guide
-====================================
+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.
 
@@ -9,20 +8,12 @@ This is the Mattermost style guide for documentation. It acts as a reference for
 
 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
+.. contents::
+  :backlinks: top
 
-  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.
+.. include:: sg_document-structure.rst
+  :start-line: 1
+.. include:: sg_grammar-spelling-mechanics.rst
+  :start-line: 1
+.. include:: sg_rest_markup.rst
+  :start-line: 1