Break up into separate files and add more content

Author: JeffSchering

source/guides/core.rst

@@ -14,8 +14,17 @@ 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
 
 Joining the Team 
 =========================
@@ -29,4 +38,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,24 @@
+==================
+Document structure
+==================
+
+Structure and organization is an important part of a document's ease of use and its understandability.
+
+Document title
+==============
+
+Use a title that accurately reflects the content of the document. People scan the table of contents looking for documents; 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.
+
+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,77 @@
+================================
+Grammar, spelling, and mechanics
+================================
+
+
+Language and spelling
+=====================
+
+Write documents in English, and use American spelling conventions.
+
+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.
+
+Good
+  The cows ran from wolves, coyotes, and mosquitoes.
+
+Not Good
+  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.
+
+Good
+  Magna Lorem duis mollit mollit minim amet proident incididunt ut consectetur.
+
+Not good
+  Sint nostrud veniam esse pariatur laboris in esse commodo aute duis deserunt amet dolore eu.
+
+.. _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, and in passive voice, the subject has an action done to it. Use passive voice when you want to emphasize the action more than the subject.
+
+Active voice
+  Veniam mollit ipsum excepteur dolore deserunt do aute incididunt nostrud enim adipisicing.
+
+Passive voice
+  Nulla est adipisicing aliquip eu dolor deserunt magna culpa consectetur.
+
+Numbers
+=======
+
+Use decimal numbers except when the number is the first word of a sentence. Use commas to make long numbers easier to read.
+
+Good
+  Three cows ran for 6 kilometers when they saw 2,300,097 mosquitoes chasing them.
+
+Text highlighting
+=================
+
+filepath - monospace (directory paths, file names)
+inline code - monospace
+code block - monospace
+Menu selection - bold
+UI selection - bold (includes buttons and links, names of controls, field names)
+text that user enters - monospace
+references - italic
+  

source/process/documentation-guidelines.rst renamed to source/process/sg_mattermost-doc-style.rst

@@ -2,41 +2,48 @@
 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.
+
+The style guide is definitely *not* intended to slow down or otherwise impede contributions, which are always welcome. No contribution will be rejected due to non-conforming style. Don't worry if you don't have time to read and comply with the guide; submit your work anyway.
+
 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.
 
-The style and tone must be consistent throughout the documentation. People need to feel confident that what they're reading is carefully attended to by its creators.  and that we have taken care and have paid attention to detail. 
+
+The reStructuredText specification allows for a certain degree of flexibility in the use of overline and underline characters to delineate sections. However, for consistency and ease of use, the Mattermost documentation should use a single convention for title underlines.
 
 
-Goals of the style guide
-========================
+Use the = character for the overline and underline. For example:
 
+::
+  
+   ==================
+   Document structure
+   ==================
 
+Note that unlike Markdown, overlines and underlines in reStructuredText must be at least as long as the title text.
 
+Section titles
+==============
 
-Document Structure
-==================
+If your document has more than one section, use the = character for the section title underline. For example:
 
-The reStructuredText specification allows for a certain degree of flexibility in the use of overline and underline characters to delineate sections. However, for consistency and ease of use, the Mattermost documentation will use the following convention:
+::
+  
+  Section titles
+  ==============
 
-Page title: overline and underline character will be the = character. For example:
-===============
-Creating a team
-===============
-equivalent to H1
+Note that in a properly chunked set of documents, with only one topic per file, you should never need more than two section levels: One for the page title, and one for each section on the page. However, we can't all reach Nirvana at once, so feel free to use subsections if they're needed.
 
-Level one headings: ============ (h2)
-Level two headings: ------------ (h3)
-Level three headings: ^^^^^^^^^^^^^ (h4)
+If you do need subsections, use the following underline characters:
 
-Note that in a properly chunked set of documents, with only one topic per file, you should never need more than two section levels: One for the page title, and one for each section on the page. However, we can't all reach Nirvana at once, so feel free to use sub sections if they're needed.
+::
+  
+  Subsection One
+  --------------
+  
+  Subsection Two
+  ``````````````
 
-filepath - monospace (directory paths, file names)
-inline code - monospace
-code block - monospace
-Menu selection - bold
-UI selection - bold (includes buttons and links, names of controls, field names)
-text that user enters - monospace
-references - italic
 
 relative links only, except of course for pages that are external to the docs
 
@@ -52,7 +59,13 @@ avoid documenting features; instead, document tasks. describe things that people
 
 simple sentences, less than 25 words.
 
+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. 
+
 Cross references
-^^^^^^^^^^^^^^^^
+================
 
 Use cross references carefully.