You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
ansible/docs/docsite/rst/dev_guide/style_guide/index.rst

168 lines
5.2 KiB
ReStructuredText

.. _style_guide:
*******************
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
-------------------
* ``^^^`` 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
basic_rules
voice_style
trademarks
grammar_punctuation
spelling_word_choice
resources
.. seealso::
: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