Welcome to the Ansible style guide! To create clear, concise, consistent, useful materials on docs.ansible.com, follow these guidelines:
We want the Ansible documentation to be:
We want reading the docs to feel like having an experienced, friendly colleague explain how Ansible works.
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 |
Headers should be written in sentence case. For example, this section’s title is
Header case, not Header Case or HEADER CASE.
The Ansible documentation is written in reStructuredText and processed by Sphinx. We follow these technical or mechanical guidelines on all rST pages:
Section headers in reStructuredText 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
""""""""""""""""""""""""""""
These pages offer more help with grammatical, stylistic, and technical rules for documentation.
See also