Ansible documentation style guide

Welcome to the Ansible style guide! To create clear, concise, consistent, useful materials on docs.ansible.com, follow these guidelines:

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

Title and heading case

Titles and headings should be written in sentence case. For example, this section’s title is Title and heading case, not Title and Heading Case or TITLE AND HEADING 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:

Heading notation

Section headings in reStructuredText can use a variety of notations. Sphinx will ‘learn on the fly’ when creating a hierarchy of headings. To make our documents easy to read and to edit, we follow a standard set of heading 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
""""""""""""""""""""""""""""

Syntax highlighting - Pygments

The Ansible documentation supports a range of Pygments lexers for syntax highlighting 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:: python

   def my_beautiful_python_code():
      pass

Internal navigation

Anchors (also called labels) and links 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 headings, can also include a local TOC.

Note

Avoid raw URLs. RST and sphinx allow https://my.example.com, but this is unhelpful for those using screen readers. :ref: links automatically pick up the heading from the anchor, but for external links, always use the `link title <link-url>`_ format.

Adding anchors

  • Include at least one anchor on every page

  • Place the main anchor above the main heading

  • 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 local TOCs

The page you’re reading includes a local TOC. 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 heading is not included

  • do not include a title

The syntax is:

.. contents::
   :local:

Markdown guidelines

Some Ansible ecosystem documentation is written in markdown and processed by mkdocs. We follow these technical or mechanical guidelines on all .md pages:

Heading notation

Section headings in markdown can use a variety of notations. To make our documents easy to read and to edit, we follow a standard set of heading notations. We use:

  • # for page titles:

# Installation
  • ## for section headings:

## Installing on Linux

Subsections add an additional # for each subsection. We recommend not going beyond #### as that suggests a deeply nested document that could present better as multiple pages.

Linking in Markdown

Using Mkdocs, you can format internal links <https://www.mkdocs.org/user-guide/writing-your-docs/#writing-with-markdown>`_ using the file name of the local file instead of an external URL.

[configuration](/configuration)

You can also link directly to a heading within a file Use the lower-case form of the heading.

[dependency](/configuration/#dependency)

External links use a similar format with the external URL.

[Ansible Documentation](https://docs.ansible.com)

Code blocks

Markdown supports code blocks in the following format.

```text
docs/
    index.md
    user-guide/getting-started.md
    user-guide/configuration-options.md
    license.md
```

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 a code block instead.

To add alt text in rst:

.. image:: path/networkdiag.png
   :width: 400
   :alt: SpiffyCorp network diagram

To add alt text in md:

![SpiffyCorp network diagram](path/networkdiag.png)

Tables

Tables have a simple, logical reading order from left to right, and top to bottom. Tables include a heading row and avoid empty or blank table cells. Label tables with a descriptive title.

For RST:

.. table:: File descriptions

  +----------+----------------------------+
  |File      |Purpose                     |
  +==========+============================+
  |foo.txt   |foo configuration settings  |
  +----------+----------------------------+
  |bar.txt   |bar configuration settings  |
  +----------+----------------------------+

For Markdown:

#### 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:

More resources

These pages offer more help with grammatical, stylistic, and technical rules for documentation.

See also

Contributing to the Ansible Documentation

How to contribute to the Ansible documentation

Testing the documentation locally

How to build the Ansible documentation

Communication

Got questions? Need help? Want to share your ideas? Visit the Ansible communication guide