Style guide index (#49746)

* First revision of ansible style guide index page

docs/docsite/rst/dev_guide/style_guide/index.rst

@@ -1,18 +1,151 @@
-.. Ansible Style Guide documentation master file, created by
-   sphinx-quickstart on Mon May 11 12:41:35 2015.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
-
 .. _style_guide:
 
 *******************
-Ansible Style Guide
+Ansible style guide
 *******************
 
-Welcome to the Ansible Style Guide
-==================================
+Welcome to the Ansible style guide!
+To create clear, concise, consistent, useful materials on docs.ansible.com, follow these guidelines:
+
+.. contents::
+   :local:
+
+Linguistic guidelines
+=====================
+
+We want the Ansible documentation to be:
+
+* clear
+* direct
+* conversational
+* easy to translate
+
+We want reading the docs to feel like having an experienced, friendly colleague
+explain how Ansible works.
+
+Stylistic cheat-sheet
+---------------------
+
+This cheat-sheet illustrates a few rules that help achieve the "Ansible tone":
+
++-------------------------------+------------------------------+----------------------------------------+
+| Rule                          | Good example                 | Bad example                            |
++===============================+==============================+========================================+
+| Use active voice              | You can run a task by        | A task can be run by                   |
++-------------------------------+------------------------------+----------------------------------------+
+| Use the present tense         | This command creates a       | This command will create a             |
++-------------------------------+------------------------------+----------------------------------------+
+| Address the reader            | As you expand your inventory | When the number of managed nodes grows |
++-------------------------------+------------------------------+----------------------------------------+
+| Use standard English          | Return to this page          | Hop back to this page                  |
++-------------------------------+------------------------------+----------------------------------------+
+| Use American English          | The color of the output      | The colour of the output               |
++-------------------------------+------------------------------+----------------------------------------+
+
+Header case
+-----------
+
+Headers should be written in sentence case. For example, this section's title is
+``Header case``, not ``Header Case`` or ``HEADER CASE``.
+
+reStructuredText guidelines
+===========================
+
+The Ansible documentation is written in reStructuredText and processed by Sphinx.
+We follow these technical or mechanical guidelines on all rST pages:
+
+Header notation
+---------------
+
+`Section headers in reStructuredText <http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#sections>`_
+can use a variety of notations.
+Sphinx will 'learn on the fly' when creating a hierarchy of headers.
+To make our documents easy to read and to edit, we follow a standard set of header notations.
+We use:
+
+* ``###`` with overline, for parts::
+
+      ###############
+      Developer guide
+      ###############
+
+* ``***`` with overline, for chapters::
+
+      *******************
+      Ansible style guide
+      *******************
+
+* ``===`` for sections::
+
+      Mechanical guidelines
+      =====================
+
+* ``---`` for subsections::
+
+      Internal navigation
+      -------------------
 
-Follow these guidelines to create clear, concise, useful community contributions and documentation. This guide helps us make the content on ansible.com consistent.
+* ``^^^`` for sub-subsections::
+
+      Adding anchors
+      ^^^^^^^^^^^^^^
+
+* ``"""`` for paragraphs::
+
+      Paragraph that needs a title
+      """"""""""""""""""""""""""""
+
+
+Internal navigation
+-------------------
+
+`Anchors (also called labels) and links <http://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#ref-role>`_
+work together to help users find related content.
+Local tables of contents also help users navigate quickly to the information they need.
+All internal links should use the ``:ref:`` syntax.
+Every page should have at least one anchor to support internal ``:ref:`` links.
+Long pages, or pages with multiple levels of headers, can also include a local TOC.
+
+Adding anchors
+^^^^^^^^^^^^^^
+
+* Include at least one anchor on every page
+* Place the main anchor above the main header
+* If the file has a unique title, use that for the main page anchor::
+
+   .. _unique_page::
+
+* You may also add anchors elsewhere on the page
+
+Adding internal links
+^^^^^^^^^^^^^^^^^^^^^
+
+* All internal links must use ``:ref:`` syntax. These links both point to the anchor defined above::
+
+   :ref:`unique_page`
+   :ref:`this page <unique_page>`
+
+The second example adds custom text for the link.
+
+Adding local TOCs
+^^^^^^^^^^^^^^^^^
+
+The page you're reading includes a `local TOC <http://docutils.sourceforge.net/docs/ref/rst/directives.html#table-of-contents>`_.
+If you include a local TOC:
+
+* place it below, not above, the main heading and (optionally) introductory text
+* use the ``:local:`` directive so the page's main header is not included
+* do not include a title
+
+The syntax is::
+
+   .. contents::
+      :local:
+
+More resources
+==============
+
+These pages offer more help with grammatical, stylistic, and technical rules for documentation.
 
 .. toctree::
   :maxdepth: 1
@@ -24,10 +157,11 @@ Follow these guidelines to create clear, concise, useful community contributions
   spelling_word_choice
   resources
 
+.. seealso::
 
-.. Indices and tables
-.. ==================
-
-.. * :ref:`genindex`
-.. * :ref:`modindex`
-.. * :ref:`search`
+   :ref:`community_documentation_contributions`
+       How to contribute to the Ansible documentation
+   :ref:`testing_documentation_locally`
+       How to build the Ansible documentation
+   `irc.freenode.net <http://irc.freenode.net>`_
+       #ansible-docs IRC chat channel