13 files changed, 1136 insertions, 0 deletions
diff --git a/docs/docsite/rst/dev_guide/style_guide/basic_rules.rst b/docs/docsite/rst/dev_guide/style_guide/basic_rules.rst
new file mode 100644
index 0000000..fcb4aba
--- /dev/null
+++ b/docs/docsite/rst/dev_guide/style_guide/basic_rules.rst
@@ -0,0 +1,71 @@
+.. _styleguide_basic:
+
+Basic rules
+===========
+.. contents::
+  :local:
+
+Use standard American English
+-----------------------------
+Ansible uses Standard American English. Watch for common words that are spelled differently in American English (color vs colour, organize vs organise, and so on).
+
+Write for a global audience
+---------------------------
+Everything you say should be understandable by people of different backgrounds and cultures. Avoid idioms and regionalism and maintain a neutral tone that cannot be misinterpreted. Avoid attempts at humor.
+
+Follow naming conventions
+-------------------------
+Always follow naming conventions and trademarks.
+
+.. good place to link to an Ansible terminology page
+
+Use clear sentence structure
+----------------------------
+Clear sentence structure means:
+
+- Start with the important information first.
+- Avoid padding/adding extra words that make the sentence harder to understand.
+- Keep it short - Longer sentences are harder to understand.
+
+Some examples of improving sentences:
+
+Bad:
+    The unwise walking about upon the area near the cliff edge may result in a dangerous fall and therefore it is recommended that one remains a safe distance to maintain personal safety.
+
+Better:
+    Danger! Stay away from the cliff.
+
+Bad:
+    Furthermore, large volumes of water are also required for the process of extraction.
+
+Better:
+    Extraction also requires large volumes of water.
+
+Avoid verbosity
+---------------
+Write short, succinct sentences. Avoid terms like:
+
+- "...as has been said before,"
+- "..each and every,"
+- "...point in time,"
+- "...in order to,"
+
+Highlight menu items and commands
+---------------------------------
+When documenting menus or commands, it helps to **bold** what is important.
+
+For menu procedures, bold the menu names, button names, and so on to help the user find them on the GUI:
+
+1. On the **File** menu, click **Open**.
+2. Type a name in the **User Name** field.
+3. In the **Open** dialog box, click **Save**.
+4. On the toolbar, click the **Open File** icon.
+
+For code or command snippets, use the RST `code-block directive <https://www.sphinx-doc.org/en/1.5/markup/code.html#directive-code-block>`_:
+
+.. code-block:: rst
+
+   .. code-block:: bash
+
+     ssh my_vyos_user@vyos.example.net
+     show config
diff --git a/docs/docsite/rst/dev_guide/style_guide/grammar_punctuation.rst b/docs/docsite/rst/dev_guide/style_guide/grammar_punctuation.rst
new file mode 100644
index 0000000..da06070
--- /dev/null
+++ b/docs/docsite/rst/dev_guide/style_guide/grammar_punctuation.rst
@@ -0,0 +1,201 @@
+
+Grammar and Punctuation 
+=======================
+
+Common Styles and Usage, and Common Mistakes
+----------------------------------------------------
+
+Ansible
+^^^^^^^
+* Write "Ansible." Not "Ansible, Inc." or "AnsibleWorks The only exceptions to this rule are when we're writing legal or financial statements.
+
+* Never use the logotype by itself in body text. Always keep the same font you are using the rest of the sentence.
+
+* A company is singular in the US. In other words, Ansible is an "it," not a "they."
+
+
+Capitalization
+^^^^^^^^^^^^^^
+If it's not a real product, service, or department at Ansible, don't capitalize it. Not even if it seems important. Capitalize only the first letter of the first word in headlines.
+
+Colon
+^^^^^
+A colon is generally used before a list or series:
+- The Triangle Area consists of three cities: Raleigh, Durham, and Chapel Hill.
+
+But not if the list is a complement or object of an element in the sentence:
+- Before going on vacation, be sure to (1) set the alarm, (2) cancel the newspaper, and (3) ask a neighbor to collect your mail.
+
+Use a colon after "as follows" and "the following" if the related list comes immediately after:
+wedge The steps for changing directories are as follows:
+
+    1. Open a terminal.
+    2. Type cd...
+
+Use a colon to introduce a bullet list (or dash, or icon/symbol of your choice):
+
+    In the Properties dialog box, you'll find the following entries:
+    
+    - Connection name
+    - Count
+    - Cost per item
+
+
+Commas
+^^^^^^
+Use serial commas, the comma before the "and" in a series of three or more items: 
+
+- "Item 1, item 2, and item 3."
+
+   
+It's easier to read that way and helps avoid confusion. The primary exception to this you will see is in PR, where it is traditional not to use serial commas because it is often the style of journalists.
+
+Commas are always important, considering the vast difference in meanings of the following two statements.
+
+- Let's eat, Grandma
+- Let's eat Grandma.
+
+Correct punctuation could save Grandma's life.
+
+If that does not convince you, maybe this will:
+
+.. image:: images/commas-matter.jpg
+
+
+Contractions
+^^^^^^^^^^^^
+Do not use contractions in Ansible documents.
+
+Em dashes
+^^^^^^^^^
+When possible, use em-dashes with no space on either side. When full em-dashes aren't available, use double-dashes with no spaces on either side--like this.
+
+A pair of em dashes can be used in place of commas to enhance readability. Note, however, that dashes are always more emphatic than commas.
+
+A pair of em dashes can replace a pair of parentheses. Dashes are considered less formal than parentheses; they are also more intrusive. If you want to draw attention to the parenthetical content, use dashes. If you want to include the parenthetical content more subtly, use parentheses.
+
+.. note::
+    When dashes are used in place of parentheses, surrounding punctuation should be omitted. Compare the following examples.
+
+::
+
+    Upon discovering the errors (all 124 of them), the publisher immediately recalled the books.
+
+    Upon discovering the errors—all 124 of them—the publisher immediately recalled the books.
+
+
+When used in place of parentheses at the end of a sentence, only a single dash is used.
+
+::
+
+    After three weeks on set, the cast was fed up with his direction (or, rather, lack of direction).
+
+    After three weeks on set, the cast was fed up with his direction—or, rather, lack of direction.
+
+
+Exclamation points (!)
+^^^^^^^^^^^^^^^^^^^^^^
+Do not use them at the end of sentences. An exclamation point can be used when referring to a command, such as the bang (!) command.
+
+Gender References
+^^^^^^^^^^^^^^^^^
+Do not use gender-specific pronouns in documentation. It is far less awkward to read a sentence that uses "they" and "their" rather than "he/she" and "his/hers." 
+
+It is fine to use "you" when giving instructions and "the user," "new users," and so on. in more general explanations. 
+
+Never use "one" in place of "you" when writing technical documentation. Using "one" is far too formal.
+
+Never use "we" when writing. "We" aren't doing anything on the user side. Ansible's products are doing the work as requested by the user.
+
+
+Hyphen
+^^^^^^
+The hyphen's primary function is the formation of certain compound terms. Do not use a hyphen unless it serves a purpose. If a compound adjective cannot be misread or, as with many psychological terms, its meaning is established, a hyphen is not necessary.
+
+Use hyphens to avoid ambiguity or confusion:
+
+::
+
+    a little-used car
+    a little used-car
+
+    cross complaint
+    cross-complaint
+
+    high-school girl
+    high schoolgirl
+
+    fine-tooth comb (most people do not comb their teeth)
+
+    third-world war
+    third world war
+
+.. image:: images/hyphen-funny.jpg
+
+In professionally printed material (particularly books, magazines, and newspapers), the hyphen is used to divide words between the end of one line and the beginning of the next. This allows for an evenly aligned right margin without highly variable (and distracting) word spacing.
+
+
+Lists
+^^^^^
+Keep the structure of bulleted lists equivalent and consistent. If one bullet is a verb phrase, they should all be verb phrases. If one is a complete sentence, they should all be complete sentences, and so on.
+
+Capitalize the first word of each bullet. Unless it is obvious that it is just a list of items, such as a list of items like:
+* computer
+* monitor
+* keyboard
+* mouse
+
+When the bulleted list appears within the context of other copy, (unless it's a straight list like the previous example) add periods, even if the bullets are sentence fragments. Part of the reason behind this is that each bullet is said to complete the original sentence.
+
+In some cases where the bullets are appearing independently, such as in a poster or a homepage promotion, they do not need periods.
+
+When giving instructional steps, use numbered lists instead of bulleted lists.
+
+
+Months and States
+^^^^^^^^^^^^^^^^^
+Abbreviate months and states according to AP. Months are only abbreviated if they are used in conjunction with a day. Example: "The President visited in January 1999." or "The President visited Jan. 12."
+
+Months: Jan., Feb., March, April, May, June, July, Aug., Sept., Nov., Dec.
+
+States: Ala., Ariz., Ark., Calif., Colo., Conn., Del., Fla., Ga., Ill., Ind., Kan., Ky., La., Md., Mass., Mich., Minn., Miss., Mo., Mont., Neb., Nev., NH, NJ, NM, NY, NC, ND, Okla., Ore., Pa., RI, SC, SD, Tenn., Vt., Va., Wash., W.Va., Wis., Wyo.
+
+Numbers
+^^^^^^^
+Numbers between one and nine are written out. 10 and above are numerals. The exception to this is writing "4 million" or "4 GB." It's also acceptable to use numerals in tables and charts.
+
+Phone Numbers
+^^^^^^^^^^^^^
+
+Phone number style: 1 (919) 555-0123 x002 and 1 888-GOTTEXT
+
+
+Quotations (Using Quotation Marks and Writing Quotes)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+     "Place the punctuation inside the quotes," the editor said.
+
+Except in rare instances, use only "said" or "says" because anything else just gets in the way of the quote itself, and also tends to editorialize.
+
+Place the name first right after the quote:
+     "I like to write first-person because I like to become the character I'm writing," Wally Lamb said. 
+
+Not:
+       "I like to write first-person because I like to become the character I'm writing," said Wally Lamb. 
+
+
+Semicolon
+^^^^^^^^^
+Use a semicolon to separate items in a series if the items contain commas:
+
+- Everyday I have coffee, toast, and fruit for breakfast; a salad for lunch; and a peanut butter sandwich, cookies, ice cream, and chocolate cake for dinner.
+
+Use a semicolon before a conjunctive adverb (however, therefore, otherwise, namely, for example, and so on):
+- I think; therefore, I am.
+
+Spacing after sentences
+^^^^^^^^^^^^^^^^^^^^^^^
+Use only a single space after a sentence.
+
+Time
+^^^^
+* Time of day is written as "4 p.m."
diff --git a/docs/docsite/rst/dev_guide/style_guide/images/commas-matter-2.jpg b/docs/docsite/rst/dev_guide/style_guide/images/commas-matter-2.jpg
new file mode 100644
index 0000000..2dec81c
--- /dev/null
+++ b/docs/docsite/rst/dev_guide/style_guide/images/commas-matter-2.jpg
diff --git a/docs/docsite/rst/dev_guide/style_guide/images/commas-matter.jpg b/docs/docsite/rst/dev_guide/style_guide/images/commas-matter.jpg
new file mode 100644
index 0000000..1699a31
--- /dev/null
+++ b/docs/docsite/rst/dev_guide/style_guide/images/commas-matter.jpg
diff --git a/docs/docsite/rst/dev_guide/style_guide/images/hyphen-funny.jpg b/docs/docsite/rst/dev_guide/style_guide/images/hyphen-funny.jpg
new file mode 100644
index 0000000..d642703
--- /dev/null
+++ b/docs/docsite/rst/dev_guide/style_guide/images/hyphen-funny.jpg
diff --git a/docs/docsite/rst/dev_guide/style_guide/images/thenvsthan.jpg b/docs/docsite/rst/dev_guide/style_guide/images/thenvsthan.jpg
new file mode 100644
index 0000000..f4851b0
--- /dev/null
+++ b/docs/docsite/rst/dev_guide/style_guide/images/thenvsthan.jpg
diff --git a/docs/docsite/rst/dev_guide/style_guide/index.rst b/docs/docsite/rst/dev_guide/style_guide/index.rst
new file mode 100644
index 0000000..b43b916
--- /dev/null
+++ b/docs/docsite/rst/dev_guide/style_guide/index.rst
@@ -0,0 +1,340 @@
+.. _style_guide:
+
+**********************************
+Ansible documentation 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``.
+
+
+Avoid using Latin phrases
+-------------------------
+
+Latin words and phrases like ``e.g.`` or ``etc.``
+are easily understood by English speakers.
+They may be harder to understand for others and are also tricky for automated translation.
+
+Use the following English terms in place of Latin terms or abbreviations:
+
++-------------------------------+------------------------------+
+| Latin                         | English                      |
++===============================+==============================+
+| i.e                           | in other words               |
++-------------------------------+------------------------------+
+| e.g.                          | for example                  |
++-------------------------------+------------------------------+
+| etc                           | and so on                    |
++-------------------------------+------------------------------+
+| via                           | by/ through                  |
++-------------------------------+------------------------------+
+| vs./versus                    | rather than/against          |
++-------------------------------+------------------------------+
+
+
+reStructuredText guidelines
+===========================
+
+The Ansible documentation is written in reStructuredText and processed by Sphinx.
+We follow these technical or mechanical guidelines on all rST pages:
+
+.. _headers_style:
+
+Header notation
+---------------
+
+`Section headers in reStructuredText <https://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:
+
+.. code-block:: rst
+
+      ###############
+      Developer guide
+      ###############
+
+* ``***`` with overline, for chapters:
+
+.. code-block:: rst
+
+      *******************
+      Ansible style guide
+      *******************
+
+* ``===`` for sections:
+
+.. code-block:: rst
+
+      Mechanical guidelines
+      =====================
+
+* ``---`` for subsections:
+
+.. code-block:: rst
+
+      Internal navigation
+      -------------------
+
+* ``^^^`` for sub-subsections:
+
+.. code-block:: rst
+
+      Adding anchors
+      ^^^^^^^^^^^^^^
+
+* ``"""`` for paragraphs:
+
+.. code-block:: rst
+
+      Paragraph that needs a title
+      """"""""""""""""""""""""""""
+
+
+Syntax highlighting - Pygments
+------------------------------
+
+The Ansible documentation supports a range of `Pygments lexers <https://pygments.org/>`_
+for `syntax highlighting <https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#code-examples>`_ to make our code examples look good. Each code-block must be correctly indented and surrounded by blank lines.
+
+The Ansible documentation allows the following values:
+
+* none (no highlighting)
+* ansible-output (a custom lexer for Ansible output)
+* bash
+* console
+* csharp
+* ini
+* json
+* powershell
+* python
+* rst
+* sh
+* shell
+* shell-session
+* text
+* yaml
+* yaml+jinja
+
+For example, you can highlight Python code using following syntax:
+
+.. code-block:: rst
+
+      .. code-block:: python
+
+         def my_beautiful_python_code():
+            pass
+
+.. _style_links:
+
+Internal navigation
+-------------------
+
+`Anchors (also called labels) and links <https://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.
+
+.. note::
+
+	Avoid raw URLs. RST and sphinx allow ::code:`https://my.example.com`, but this is unhelpful for those using screen readers. ``:ref:`` links automatically pick up the header from the anchor, but for external links, always use the ::code:`link title <link-url>`_` format.
+
+.. _adding_anchors_rst:
+
+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:
+
+.. code-block:: text
+
+   .. _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:
+
+.. code-block:: rst
+
+   :ref:`unique_page`
+   :ref:`this page <unique_page>`
+
+The second example adds custom text for the link.
+
+Adding links to modules and plugins
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Ansible 2.10 and later require the extended Fully Qualified Collection Name (FQCN) as part of the links:
+
+.. code-block:: text
+
+  ansible_collections. + FQCN + _module
+
+For example:
+
+  .. code-block:: rst
+
+   :ref:`ansible.builtin.first_found lookup plugin <ansible_collections.ansible.builtin.first_found_lookup>`
+
+displays as :ref:`ansible.builtin.first_found lookup plugin <ansible_collections.ansible.builtin.first_found_lookup>`.
+
+Modules require different suffixes from other plugins:
+
+* Module links use this extended FQCN module name with ``_module`` for the anchor.
+* Plugin links use this extended FQCN plugin name with the plugin type (``_connection`` for example).
+
+.. code-block:: rst
+
+   :ref:`arista.eos.eos_config <ansible_collections.arista.eos.eos_config_module>`
+   :ref:`kubernetes.core.kubectl connection plugin <ansible_collections.kubernetes.core.kubectl_connection>`
+
+.. note::
+
+	``ansible.builtin`` is the FQCN for modules included in ``ansible.base``. Documentation links are the only place you prepend ``ansible_collections`` to the FQCN. This is used by the documentation build scripts to correctly fetch documentation from collections on Ansible Galaxy.
+
+.. _local_toc:
+
+Adding local TOCs
+^^^^^^^^^^^^^^^^^
+
+The page you're reading includes a `local TOC <https://docutils.sourceforge.io/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:
+
+.. code-block:: rst
+
+   .. contents::
+      :local:
+
+Accessibility guidelines
+=========================
+
+Ansible documentation has a goal to be more accessible. Use the following guidelines to help us reach this goal.
+
+Images and alternative text
+  Ensure all icons, images, diagrams, and non text elements have a meaningful alternative-text description. Do not include screen captures of CLI output. Use ``code-block`` instead.
+
+  .. code-block:: text
+
+    .. image:: path/networkdiag.png
+       :width: 400
+       :alt: SpiffyCorp network diagram
+
+
+Links and hypertext
+  URLs and cross-reference links have descriptive text that conveys information about the content of the linked target. See :ref:`style_links` for how to format links.
+
+Tables
+  Tables have a simple, logical reading order from left to right, and top to bottom.
+  Tables include a header row and avoid empty or blank table cells.
+  Label tables with a descriptive title.
+
+  .. code-block:: reStructuredText
+
+    .. table:: File descriptions
+
+      +----------+----------------------------+
+      |File      |Purpose                     |
+      +==========+============================+
+      |foo.txt   |foo configuration settings  |
+      +----------+----------------------------+
+      |bar.txt   |bar configuration settings  |
+      +----------+----------------------------+
+
+
+Colors and other visual information
+  * Avoid instructions that rely solely on sensory characteristics. For example, do not use ``Click the square, blue button to continue.``
+  * Convey information by methods and not by color alone.
+  * Ensure there is sufficient contrast between foreground and background text or graphical elements in images and diagrams.
+  * Instructions for navigating through an interface make sense without directional indicators such as left, right, above, and below.
+
+Accessibility resources
+------------------------
+
+Use the following resources to help test your documentation changes:
+
+* `axe DevTools browser extension <https://chrome.google.com/webstore/detail/axe-devtools-web-accessib/lhdoppojpmngadmnindnejefpokejbdd?hl=en-US&_ga=2.98933278.1490638154.1645821120-953800914.1645821120>`_ - Highlights accessibility issues on a website page.
+* `WAVE browser extension <https://wave.webaim.org/extension/>`_ from WebAIM  - another accessibility tester.
+* `Orca screen reader <https://help.gnome.org/users/orca/stable/>`_ - Common tool used by people with vision impairments.
+* `color filter <https://www.toptal.com/designers/colorfilter/>`_ - For color-blind testing.
+
+More resources
+==============
+
+These pages offer more help with grammatical, stylistic, and technical rules for documentation.
+
+.. toctree::
+  :maxdepth: 1
+
+  basic_rules
+  voice_style
+  trademarks
+  grammar_punctuation
+  spelling_word_choice
+  search_hints
+  resources
+
+.. seealso::
+
+   :ref:`community_documentation_contributions`
+       How to contribute to the Ansible documentation
+   :ref:`testing_documentation_locally`
+       How to build the Ansible documentation
+   `irc.libera.chat <https://libera.chat>`_
+       #ansible-docs IRC chat channel
diff --git a/docs/docsite/rst/dev_guide/style_guide/resources.rst b/docs/docsite/rst/dev_guide/style_guide/resources.rst
new file mode 100644
index 0000000..64dc0c1
--- /dev/null
+++ b/docs/docsite/rst/dev_guide/style_guide/resources.rst
@@ -0,0 +1,11 @@
+Resources
+^^^^^^^^^
+* Follow the style of the :ref:`Ansible Documentation<ansible_documentation>`
+* Ask for advice on the ``#ansible-devel`` chat channel (using Matrix at ansible.im or using IRC at `irc.libera.chat <https://libera.chat/>`_)
+* Review these online style guides:
+
+  * `AP Stylebook <https://www.apstylebook.com>`_
+  * `Chicago Manual of Style <https://www.chicagomanualofstyle.org/home.html>`_
+  * `Strunk and White's Elements of Style <https://www.crockford.com/wrrrld/style.html>`_
+  * `Google developer documentation style guide <https://developers.google.com/style/highlights>`_
+
diff --git a/docs/docsite/rst/dev_guide/style_guide/search_hints.rst b/docs/docsite/rst/dev_guide/style_guide/search_hints.rst
new file mode 100644
index 0000000..d9bf3f6
--- /dev/null
+++ b/docs/docsite/rst/dev_guide/style_guide/search_hints.rst
@@ -0,0 +1,48 @@
+
+.. _search_hints:
+
+Writing documentation so search can find it
+-------------------------------------------
+
+One of the keys to writing good documentation is to make it findable. Readers use a combination of internal site search and external search engines such as Google or duckduckgo.
+
+To ensure Ansible documentation is findable, you should:
+
+#. Use headings that clearly reflect what you are documenting.
+#. Use numbered lists for procedures or high-level steps where possible.
+#. Avoid linking to github blobs where possible.
+
+
+Using clear headings in documentation
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+We all use simple English when we want to find something. For example, the title of this page could have been any one of the following:
+
+* Search optimization
+* Findable documentation
+* Writing for findability
+
+What we are really trying to describe is - how do I write documentation so search engines can find my content? That simple phrase is what drove the title of this section. When you are creating your headings for documentation, spend some time to think about what you would type in a search box to find it, or more importantly, how someone less familiar with Ansible would try to find that information. Your heading should be the answer to that question.
+
+One word of caution - you do want to limit the size of your headings. A full heading such as `How do I write documentation so search engines can find my content?` is too long. Search engines would truncate anything over 50 - 60 characters. Long headings would also wrap on smaller devices such as a smart phone.
+
+Using numbered lists for `zero position` snippets
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Google can optimize the search results by adding a `feature snippet <https://support.google.com/websearch/answer/9351707>`_ at the top of the search results. This snippet provides a small window into the documentation on that first search result that adds more detail than the rest of the search results, and can occasionally answer the reader's questions right there, or at least verify that the linked page is what the reader is looking for.
+
+Google returns the feature snippet in the form of numbered steps. Where possible, you should add a numbered list near the top of your documentation page, where appropriate. The steps can be the exact procedure a reader would follow, or could be a high level introduction to the documentation topic, such as the numbered list at the top of this page.
+
+Problems with github blobs on search results
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Search engines do not typically return github blobs in search results, at least not in higher ranked positions. While it is possible and sometimes necessary to link to github blobs from documentation, the better approach would be to copy that information into an .rst page in Ansible documentation.
+
+Other search hints
+^^^^^^^^^^^^^^^^^^
+
+While it may not be possible to adapt your documentation to all search optimizations, keep the following in mind as you write your documentation:
+
+* **Search engines don't parse beyond the `#` in an html page.** So for example, all the subheadings on this page are appended to the main page URL. As such, when I search for 'Using number lists for zero position snippets', the search result would be a link to the top of this page, not a link directly to the subheading I searched for. Using :ref:`local TOCs <local_toc>` helps alleviate this problem as the reader can scan for the header at top of the page and click to the section they are looking for. For critical documentation, consider creating a new page that can be a direct search result page.
+
+* **Make your first few sentences clearly describe your page topic.** Search engines return not just the URL, but a short description of the information at the URL. For Ansible documentation, we do not have description metadata embedded on each page. Instead, the search engines return the first couple of sentences (140 characters) on the page. That makes your first sentence or two very important to the reader who is searching for something in Ansible.
diff --git a/docs/docsite/rst/dev_guide/style_guide/spelling_word_choice.rst b/docs/docsite/rst/dev_guide/style_guide/spelling_word_choice.rst
new file mode 100644
index 0000000..ce16eba
--- /dev/null
+++ b/docs/docsite/rst/dev_guide/style_guide/spelling_word_choice.rst
@@ -0,0 +1,327 @@
+Spelling - Word Usage - Common Words and Phrases to Use and Avoid
+-----------------------------------------------------------------
+
+Acronyms
+^^^^^^^^
+
+Always uppercase. An acronym is a word formed from the initial letters of a name, such as ROM for Read-only memory,
+SaaS for Software as a Service, or by combining initial letters or part of a series of words, such as LILO for LInux
+LOader.
+
+Spell out the acronym before using it in alone text, such as "The Embedded DevKit (EDK)..."
+
+Applications
+^^^^^^^^^^^^
+When used as a proper name, use the capitalization of the product, such as GNUPro or Source-Navigator. When used as a command, use lowercase as appropriate, such as "To start GCC, type ``gcc``."
+
+.. note::
+
+    "vi" is always lowercase.
+
+As
+^^
+This is often used to mean "because", but has other connotations, for example, parallel or simultaneous actions. If you mean "because", say "because".
+
+Asks for
+^^^^^^^^
+Use "requests" instead.
+
+Assure/Ensure/Insure
+^^^^^^^^^^^^^^^^^^^^
+Assure implies a sort of mental comfort. As in "I assured my husband that I would eventually bring home beer."
+
+Ensure means "to make sure."
+
+Insure relates to monetary insurance.
+
+
+Back up
+^^^^^^^
+This is a verb. You "back up" files; you do not "backup" files.
+
+Backup
+^^^^^^
+This is a noun. You create "backup" files; you do not create "back up" files.
+
+Backward
+^^^^^^^^
+Correct. Avoid using backwards unless you are stating that something has "backwards compatibility."
+
+Backwards compatibility
+^^^^^^^^^^^^^^^^^^^^^^^
+Correct as is.
+
+By way of
+^^^^^^^^^
+Use "using" instead.
+
+Can/May
+^^^^^^^
+Use "can" to describe actions or conditions that are possible. Use "may" only to describe situations where permission is being given. If either "can," "could," or "may" apply, use "can" because it's less tentative.
+
+CD or cd
+^^^^^^^^
+When referring to a compact disk, use CD, such as "Insert the CD into the CD-ROM drive." When referring to the change directory command, use cd. 
+
+CD-ROM
+^^^^^^
+Correct. Do not use "cdrom," "CD-Rom," "CDROM," "cd-rom" or any other variation. When referring to the drive, use CD-ROM drive, such as "Insert the CD into the CD-ROM drive." The plural is "CD-ROMs."
+
+
+Command line
+^^^^^^^^^^^^
+Correct. Do not use "command-line" or "commandline" as a noun. If used as an adjective, "command-line" is appropriate, for example "command-line arguments".
+
+Use "command line" to describes where to place options for a command, but not where to type the command. Use "shell prompt" instead to describe where to type commands. The line on the display screen where a command is expected. Generally, the command line is the line that contains the most recently displayed command prompt.
+
+
+Daylight saving time (DST)
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Correct. Do not use daylight savings time. Daylight Saving Time (DST) is often misspelled "Daylight Savings", with an "s" at the end. Other common variations are "Summer Time"and "Daylight-Saving Time". (https://www.timeanddate.com/time/dst/daylight-savings-time.html)
+
+
+Download
+^^^^^^^^
+Correct. Do not use "down load" or "down-load."
+
+e.g.
+^^^^
+Spell it out: "For example."
+
+Failover
+^^^^^^^^
+When used as a noun, a failover is a backup operation that automatically switches to a standby database, server or network if the primary system fails or is temporarily shut down for servicing. Failover is an important fault tolerance function of mission-critical systems that rely on constant accessibility. Failover automatically and transparently to the user redirects requests from the failed or down system to the backup system that mimics the operations of the primary system.
+
+Fail over
+^^^^^^^^^
+When used as a verb, fail over is two words since there can be different tenses such as failed over.
+
+Fewer
+^^^^^
+Fewer is used with plural nouns. Think things you could count.  Time, money, distance, and weight are often listed as exceptions to the traditional "can you count it" rule, often thought of a singular amounts (the work will take less than 5 hours, for example).
+
+File name
+^^^^^^^^^
+Correct. Do not use "filename."
+
+File system
+^^^^^^^^^^^
+Correct. Do not use "filesystem." The system that an operating system or program uses to organize and keep track of files. For example, a hierarchical file system is one that uses directories to organize files into a tree structure. Although the operating system provides its own file management system, you can buy separate file management systems. These systems interact smoothly with the operating system but provide more features, such as improved backup procedures and stricter file protection.
+
+For instance
+^^^^^^^^^^^^
+For example," instead.
+
+For further/additional/whatever information
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Use "For more information"
+
+For this reason
+^^^^^^^^^^^^^^^
+Use "therefore".
+
+Forward
+^^^^^^^
+Correct. Avoid using "forwards."
+
+Gigabyte (GB)
+^^^^^^^^^^^^^
+2 to the 30th power (1,073,741,824) bytes. One gigabyte is equal to 1,024 megabytes. Gigabyte is often abbreviated as G or GB.
+
+Got
+^^^
+Avoid. Use "must" instead.
+
+High-availability
+^^^^^^^^^^^^^^^^^
+Correct. Do not use "high availability."
+
+Highly available
+^^^^^^^^^^^^^^^^
+Correct. Do not use highly-available."
+
+Hostname
+^^^^^^^^
+Correct. Do not use host name.
+
+i.e.
+^^^^
+Spell it out: "That is."
+
+Installer
+^^^^^^^^^
+Avoid. Use "installation program" instead.
+
+It's and its
+^^^^^^^^^^^^
+"It's" is a contraction for "it is;" use "it is" instead of "it's." Use "its" as a possessive pronoun (for example, "the store is known for its low prices").
+
+Less
+^^^^
+Less is used with singular nouns. For example "View less details" wouldn't be correct but "View less detail" works. Use fewer when you have plural nouns (things you can count).
+
+Linux
+^^^^^
+Correct. Do not use "LINUX" or "linux" unless referring to a command, such as "To start Linux, type linux." Linux is a registered trademark of Linus Torvalds.
+
+Login
+^^^^^
+A noun used to refer to the login prompt, such as "At the login prompt, enter your username."
+
+Log in
+^^^^^^
+A verb used to refer to the act of logging in. Do not use "login," "loggin," "logon," and other variants. For example, "When starting your computer, you are requested to log in..."
+
+Log on
+^^^^^^
+To make a computer system or network recognize you so that you can begin a computer session. Most personal computers have no log-on procedure -- you just turn the machine on and begin working. For larger systems and networks, however, you usually need to enter a username and password before the computer system will allow you to execute programs.
+
+Lots of
+^^^^^^^
+Use "Several" or something equivalent instead.
+
+Make sure
+^^^^^^^^^
+This means "be careful to remember, attend to, or find out something." For example, "...make sure that the rhedk group is listed in the output."
+Try to use verify or ensure instead.
+
+Manual/man page
+^^^^^^^^^^^^^^^
+Correct. Two words. Do not use "manpage"
+
+MB
+^^
+(1) When spelled MB, short for megabyte (1,000,000 or 1,048,576 bytes, depending on the context).
+(2) When spelled Mb, short for megabit.
+
+MBps
+^^^^
+Short for megabytes per second, a measure of data transfer speed. Mass storage devices are generally measured in MBps.
+
+MySQL
+^^^^^
+Common open source database server and client package. Do not use "MYSQL" or "mySQL."
+
+Need to
+^^^^^^^
+Avoid. Use "must" instead.
+
+Read-only
+^^^^^^^^^
+Correct. Use when referring to the access permissions of files or directories.
+
+Real time/real-time
+^^^^^^^^^^^^^^^^^^^
+Depends. If used as a noun, it is the actual time during which something takes place. For example, "The computer may partly analyze the data in real time (as it comes in) -- R. H. March." If used as an adjective, "real-time" is appropriate. For example, "XEmacs is a self-documenting, customizable, extensible, real-time display editor."
+
+Refer to
+^^^^^^^^
+Use to indicate a reference (within a manual or website) or a cross-reference (to another manual or documentation source).
+
+See
+^^^
+Don't use. Use "Refer to" instead.
+
+Since
+^^^^^
+This is often used to mean "because", but "since" has connotations of time, so be careful. If you mean "because", say "because".
+
+Tells
+^^^^^
+Use "Instructs" instead.
+
+That/which
+^^^^^^^^^^
+"That" introduces a restrictive clause-a clause that must be there for the sentence to make sense. A restrictive clause often defines the noun or phrase preceding it. "Which" introduces a non-restrictive, parenthetical clause-a clause that could be omitted without affecting the meaning of the sentence. For example: The car was travelling at a speed that would endanger lives. The car, which was traveling at a speed that would endanger lives, swerved onto the sidewalk. Use "who" or "whom," rather than "that" or "which," when referring to a person.
+
+Then/than
+^^^^^^^^^
+ "Then" refers to a time in the past or the next step in a sequence. "Than" is used for comparisons.
+
+.. image:: images/thenvsthan.jpg
+
+Third-party
+^^^^^^^^^^^
+Correct. Do not use "third party".
+
+Troubleshoot
+^^^^^^^^^^^^
+Correct. Do not use "trouble shoot" or "trouble-shoot." To isolate the source of a problem and fix it. In the case of computer systems, the term troubleshoot is usually used when the problem is suspected to be hardware -related. If the problem is known to be in software, the term debug is more commonly used.
+
+UK
+^^
+Correct as is, no periods.
+
+UNIX®
+^^^^^
+Correct. Do not use "Unix" or "unix." UNIX® is a registered trademark of The Open Group.
+
+Unset
+^^^^^
+Don't use. Use Clear.
+
+US
+^^
+Correct as is, no periods.
+
+User
+^^^^
+When referring to the reader, use "you" instead of "user." For example, "The user must..." is incorrect. Use "You must..." instead. If referring to more than one user, calling the collection "users" is acceptable, such as "Other users may wish to access your database."
+
+Username
+^^^^^^^^
+Correct. Do not use "user name."
+
+View
+^^^^
+When using as a reference ("View the documentation available online."), do not use View. Use "Refer to" instead.
+
+Within
+^^^^^^
+Don't use to refer to a file that exists in a directory. Use "In".
+
+World Wide Web
+^^^^^^^^^^^^^^
+Correct. Capitalize each word. Abbreviate as "WWW" or "Web."
+
+Webpage
+^^^^^^^
+Correct. Do not use "web page" or "Web page."
+
+Web server
+^^^^^^^^^^
+Correct. Do not use "webserver". For example, "The Apache HTTP Server is the default Web server..."
+ 
+Website
+^^^^^^^
+Correct. Do not use "web site" or "Web site." For example, "The Ansible website contains ..."
+
+Who/whom
+^^^^^^^^
+Use the pronoun "who" as a subject. Use the pronoun "whom" as a direct object, an indirect object, or the object of a preposition. For example: Who owns this? To whom does this belong?
+
+Will
+^^^^
+Do not use future tense unless it is absolutely necessary. For instance, do not use the sentence, "The next section will describe the process in more detail." Instead, use the sentence, "The next section describes the process in more detail."
+
+Wish
+^^^^
+Use "need" instead of "desire" and "wish." Use "want" when the reader's actions are optional (that is, they may not "need" something but may still "want" something).
+
+x86
+^^^
+Correct. Do not capitalize the "x."
+
+x86_64
+^^^^^^
+Do not use. Do not use "Hammer". Always use "AMD64 and Intel® EM64T" when referring to this architecture.
+
+You
+^^^
+Correct. Do not use "I," "he," or "she."
+
+You may
+^^^^^^^
+Try to avoid using this. For example, "you may" can be eliminated from this sentence "You may double-click on the desktop..."
+
diff --git a/docs/docsite/rst/dev_guide/style_guide/trademarks.rst b/docs/docsite/rst/dev_guide/style_guide/trademarks.rst
new file mode 100644
index 0000000..6e1fb27
--- /dev/null
+++ b/docs/docsite/rst/dev_guide/style_guide/trademarks.rst
@@ -0,0 +1,95 @@
+
+Trademark Usage
+---------------
+Why is it important to use the TM, SM, and ® for our registered marks?
+
+Before a trademark is registered with the United States Patent and Trademark Office it is appropriate to use the TM or SM symbol depending whether the product is for goods or services. It is important to use the TM or SM as it is notification to the public that Ansible claims rights to the mark even though it has not yet been registered. 
+
+Once the trademark is registered, it is appropriate to use the symbol in place of the TM or SM. The symbol designation must be used in conjunction with the trademark if Ansible is to fully protect its rights. If we don't protect these marks, we run the risk of losing them in the way of Aspirin or Trampoline or Escalator.
+
+General Rules: 
+^^^^^^^^^^^^^^
+
+Trademarks should be used on 1st references on a page or within a section.
+
+Use Red Hat® Ansible® Automation Platform or Ansible®, on first reference when referring to products.
+ 
+Use "Ansible" alone as the company name, as in "Ansible announced quarterly results," which is not marked.
+
+Also add the trademark disclaimer.
+* When using Ansible trademarks in the body of written text, you should use the following credit line in a prominent place, usually a footnote.
+
+    For Registered Trademarks:
+    - [Name of Trademark] is a registered trademark of Red Hat, Inc. in the United States and other countries.
+    
+    For Unregistered Trademarks (TMs/SMs):
+    - [Name of Trademark] is a trademark of Red Hat, Inc. in the United States and other countries.
+
+    For registered and unregistered trademarks:
+    - [Name of Trademark] is a registered trademark and [Name of Trademark] is a trademark of Red Hat, Inc. in the United States and other countries.
+
+Guidelines for the proper use of trademarks:
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+ 
+ Always distinguish trademarks from surround text with at least initial capital letters or in all capital letters.
+
+Always use proper trademark form and spelling.
+
+Never use a trademark as a noun. Always use a trademark as an adjective modifying the noun.
+
+    Correct:
+    Red Hat® Ansible® Automation Platform system performance is incredible.
+
+    Incorrect:
+    Ansible's performance is incredible.
+    
+Never use a trademark as a verb. Trademarks are products or services, never actions.
+
+    Correct:
+    "Orchestrate your entire network using Red Hat® Ansible® Automation Platform."
+    
+    Incorrect:
+    "Ansible your entire network."
+
+Never modify a trademark to a plural form. Instead, change the generic word from the singular to the plural.
+
+    Correct:
+    "Corporate demand for Red Hat® Ansible® Automation Platform software is surging."
+
+    Incorrect:
+    "Corporate demand for Ansible is surging."
+    
+Never modify a trademark from its possessive form, or make a trademark possessive. Always use it in the form it has been registered.
+
+Never translate a trademark into another language.
+
+Never use trademarks to coin new words or names.
+
+Never use trademarks to create a play on words.
+
+Never alter a trademark in any way including through unapproved fonts or visual identifiers.
+
+Never abbreviate or use any Ansible trademarks as an acronym.
+
+The importance of Ansible trademarks
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The Ansible trademark and the "A" logo in a shaded circle are our most valuable assets. The value of these trademarks encompass the Ansible Brand. Effective trademark use is more than just a name, it defines the level of quality the customer will receive and it ties a product or service to a corporate image. A trademark may serve as the basis for many of our everyday decisions and choices. The Ansible Brand is about how we treat customers and each other. In order to continue to build a stronger more valuable Brand we must use it in a clear and consistent manner.
+
+The mark consists of the letter "A" in a shaded circle. As of 5/11/15, this was a pending trademark (registration in process).
+
+Common Ansible Trademarks
+^^^^^^^^^^^^^^^^^^^^^^^^^
+* Ansible®
+
+Other Common Trademarks and Resource Sites:
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+- Linux is a registered trademark of Linus Torvalds.
+- UNIX® is a registered trademark of The Open Group.
+- Microsoft, Windows, Vista, XP, and NT are registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries. https://www.microsoft.com/en-us/legal/intellectualproperty/trademarks/en-us.aspx
+- Apple, Mac, Mac OS, Macintosh, Pages and TrueType are either registered trademarks or trademarks of Apple Computer, Inc. in the United States and/or other countries. https://www.apple.com/legal/intellectual-property/trademark/appletmlist.html
+- Adobe, Acrobat, GoLive, InDesign, Illustrator, PostScript , PhotoShop and the OpenType logo are either registered trademarks or trademarks of Adobe Systems Incorporated in the United States and/or other countries. https://www.adobe.com/legal/permissions/trademarks.html
+- Macromedia and Macromedia Flash are trademarks of Macromedia, Inc. https://www.adobe.com/legal/permissions/trademarks.html
+- IBM is a registered trademark of International Business Machines Corporation. https://www.ibm.com/legal/us/en/copytrade.shtml
+- Celeron, Celeron Inside, Centrino, Centrino logo, Core Inside, Intel Core, Intel Inside, Intel Inside logo, Itanium, Itanium Inside, Pentium, Pentium Inside,VTune, Xeon, and Xeon Inside are trademarks or registered trademarks of Intel Corporation or its subsidiaries in the United States and other countries. https://www.intel.com/content/www/us/en/legal/trademarks.html
+
diff --git a/docs/docsite/rst/dev_guide/style_guide/voice_style.rst b/docs/docsite/rst/dev_guide/style_guide/voice_style.rst
new file mode 100644
index 0000000..b15029d
--- /dev/null
+++ b/docs/docsite/rst/dev_guide/style_guide/voice_style.rst
@@ -0,0 +1,20 @@
+
+Voice Style
+===========
+The essence of the Ansible writing style is short sentences that flow naturally together. Mix up sentence structures. Vary sentence subjects. Address the reader directly. Ask a question. And when the reader adjusts to the pace of shorter sentences, write a longer one.
+
+- Write how real people speak...
+- ...but try to avoid slang and colloquialisms that might not translate well into other languages.
+- Say big things with small words.
+- Be direct. Tell the reader exactly what you want them to do.
+- Be honest.
+- Short sentences show confidence.
+- Grammar rules are meant to be bent, but only if the reader knows you are doing this.
+- Choose words with fewer syllables for faster reading and better understanding.
+- Think of copy as one-on-one conversations rather than as a speech. It's more difficult to ignore someone who is speaking to you directly.
+- When possible, start task-oriented sentences (those that direct a user to do something) with action words. For example: Find software... Contact support... Install the media.... and so forth.
+
+Active Voice
+------------
+Use the active voice ("Start Linuxconf by typing...") rather than passive ("Linuxconf can be started by typing...") whenever possible. Active voice makes for more lively, interesting reading.
+Also avoid future tense (or using the term "will") whenever possible For example, future tense ("The screen will display...") does not read as well as an active voice ("The screen displays"). Remember, the users you are writing for most often refer to the documentation while they are using the system, not after or in advance of using the system.
diff --git a/docs/docsite/rst/dev_guide/style_guide/why_use.rst b/docs/docsite/rst/dev_guide/style_guide/why_use.rst
new file mode 100644
index 0000000..8ed840a
--- /dev/null
+++ b/docs/docsite/rst/dev_guide/style_guide/why_use.rst
@@ -0,0 +1,23 @@
+:orphan:
+
+Why Use a Style Guide?
+""""""""""""""""""""""
+
+Style guides are important because they ensure consistency in the content, look, and feel of a book or a website.
+
+Remember, a style guide is only useful if it is used, updated, and enforced.  Style Guides are useful for engineering-related documentation, sales and marketing materials, support docs, community contributions, and more.
+
+As changes are made to the overall Ansible site design, be sure to update this style guide with those changes. Or, should other resources listed below have major revisions, consider including company information here for ease of reference.
+
+This style guide incorporates current Ansible resources and information so that overall site and documentation consistency can be met.
+
+.. raw:: html
+
+   <blockquote class="note info">
+
+   "If you don't find it in the index, look very carefully through the entire catalogue."
+    ― Sears, Roebuck and Co., 1897 Sears Roebuck & Co. Catalogue
+
+.. raw:: html
+
+   </blockquote>