Merge pull request #793 from mattermost/style-guide-updates

Style Guide Updates

Author: Eric Sethna

source/guides/core.rst

@@ -14,7 +14,6 @@ Development Process
    /process/release-process*
    /process/accepting-pull-request*
    /process/community-systems*
-   /process/documentation-guidelines*
    /process/marketing-guidelines*
 
 Documentation Style Guide
@@ -23,7 +22,7 @@ Documentation Style Guide
 .. toctree::
    :maxdepth: 3
 
-   /process/mattermost-doc-style.rst
+   /process/documentation-guidelines*
 
 Joining the Team 
 -------------------------

source/process/documentation-guidelines.md

@@ -1,4 +1,4 @@
-Document structure
+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.
@@ -7,23 +7,26 @@ 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
+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
+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.
+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 three 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
+Table of Contents
+------------------
+
+If the document contains more than four sections or subsections, add a table of contents to help the user navigate the document, see :ref:`table-of-contents`.
+
+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.