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