Ansible style guide¶
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:
- easy to translate
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
Latin words and phrases like
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:
|i.e||in other words|
|etc||and so on|
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 *******************
Mechanical guidelines =====================
Internal navigation -------------------
Adding anchors ^^^^^^^^^^^^^^
Paragraph that needs a title """"""""""""""""""""""""""""
These pages offer more help with grammatical, stylistic, and technical rules for documentation.