Writing style updates to Using Variables topic (#71194)

* updated topic title, underline length for headings, and incorporated peer feedback

docs/docsite/rst/user_guide/playbooks_variables.rst

@@ -6,7 +6,7 @@ Using Variables
 
 Ansible uses variables to manage differences between systems. With Ansible, you can execute tasks and playbooks on multiple different systems with a single command. To represent the variations among those different systems, you can create variables with standard YAML syntax, including lists and dictionaries. You can set these variables in your playbooks, in your :ref:`inventory <intro_inventory>`, in re-usable :ref:`files <playbooks_reuse>` or :ref:`roles <playbooks_reuse_roles>`, or at the command line. You can also create variables during a playbook run by registering the return value or values of a task as a new variable.
 
-You can use the variables you created in module arguments, in :ref:`conditional "when" statements <playbooks_conditionals>`, in :ref:`templates <playbooks_templating>`, and in :ref:`loops <playbooks_loops>`. The `ansible-examples github repository <https://github.com/ansible/ansible-examples>`_ contains many examples of using variables in Ansible.
+You can create variables with standard YAML syntax, including lists and dictionaries. You can also create variables during a playbook run by registering the return value or values of a task as a new variable.  You can use the variables that you created in module arguments, in :ref:`conditional "when" statements <playbooks_conditionals>`, in :ref:`templates <playbooks_templating>`, and in :ref:`loops <playbooks_loops>`. The `ansible-examples github repository <https://github.com/ansible/ansible-examples>`_ contains many examples of using variables in Ansible.
 
 Once you understand the concepts and examples on this page, read about :ref:`Ansible facts <vars_and_facts>`, which are variables you retrieve from remote systems.
 
@@ -18,10 +18,12 @@ Once you understand the concepts and examples on this page, read about :ref:`Ans
 Creating valid variable names
 =============================
 
-Not all strings are valid Ansible variable names. A variable name can only include letters, numbers, and underscores. `Python keywords`_ and :ref:`playbook keywords<playbook_keywords>` are not valid variable names. A variable name cannot begin with a number.
+Not all strings are valid Ansible variable names. A variable name can only include letters, numbers, and underscores. `Python keywords`_ or :ref:`playbook keywords<playbook_keywords>` are not valid variable names. A variable name cannot begin with a number. 
 
 Variable names can begin with an underscore. In many programming languages, variables that begin with an underscore are private. This is not true in Ansible. Variables that begin with an underscore are treated exactly the same as any other variable. Do not rely on this convention for privacy or security.
 
+The table below gives examples of valid and invalid variable names:
+
 .. table::
    :class: documentation-table
 
@@ -42,7 +44,7 @@ Variable names can begin with an underscore. In many programming languages, vari
 Simple variables
 ================
 
-Simple variables combine a variable name with a single value. You can use this syntax (and the syntax for lists and dictionaries shown below) in a variety of places. See :ref:`setting_variables` for information on where to set variables.
+Simple variables combine a variable name with a single value. You can use this syntax (and the syntax for lists and dictionaries shown below) in a variety of places. For details about setting the variables in inventory, in playbooks, in reusable files, in roles, or at the command line, see :ref:`setting_variables` for information on where to set variables.
 
 Defining simple variables
 -------------------------
@@ -69,7 +71,7 @@ In this example, the variable defines the location of a file, which can vary fro
 When to quote variables (a YAML gotcha)
 =======================================
 
-If you start a value with ``{{ foo }}``, you must quote the whole expression to create valid YAML syntax. If you do not quote the whole expression, the YAML parser cannot interpret the syntax - it might be a variable or it might be the start of a YAML dictionary. See the :ref:`yaml_syntax` documentation for more guidance on writing YAML.
+If you start a value with ``{{ foo }}``, you must quote the whole expression to create valid YAML syntax. If you do not quote the whole expression, the YAML parser cannot interpret the syntax - it might be a variable or it might be the start of a YAML dictionary. For guidance on writing YAML, see the :ref:`yaml_syntax` documentation.
 
 If you use a variable without quotes like this::
 
@@ -83,6 +85,15 @@ You will see: ``ERROR! Syntax Error while loading YAML.`` If you add quotes, Ans
       vars:
            app_path: "{{ base_path }}/22"
 
+.. _list_variables:
+
+List variables
+==============
+
+A list variable combines a variable name with multiple values. The multiple values are stored in a square bracket [] and are separated with commas.
+
+
+
 Defining variables as lists
 ---------------------------
 
@@ -102,9 +113,13 @@ When you use variables defined as a list (also called an array), you can use ind
 
 The value of this expression would be "northeast".
 
+.. _dictionary_variables:
+
 Dictionary variables
 ====================
 
+A dictionary stores the data in key-value pairs. Usually, dictionaries are used to store related data, such as the information contained in an ID or a user profile.
+
 Defining variables as key:value dictionaries
 --------------------------------------------
 
@@ -161,7 +176,7 @@ Many registered variables (and :ref:`facts <vars_and_facts>`) are nested YAML or
 
     {{ ansible_facts["eth0"]["ipv4"]["address"] }}
 
-Using the dot notation::
+To reference an IP address from your facts by using the dot notation::
 
     {{ ansible_facts.eth0.ipv4.address }}
 
@@ -171,26 +186,26 @@ Using the dot notation::
 Transforming variables with Jinja2 filters
 ==========================================
 
-Jinja2 filters let you transform the value of a variable within a template expression. For example, the ``capitalize`` filter capitalizes any value passed to it; the ``to_yaml`` and ``to_json`` filters change the format of your variable values. Jinja2 includes many `built-in filters <http://jinja.pocoo.org/docs/templates/#builtin-filters>`_ and Ansible supplies many more filters. See :ref:`playbooks_filters` for examples.
+Jinja2 filters let you transform the value of a variable within a template expression. For example, the ``capitalize`` filter capitalizes any value passed to it; the ``to_yaml`` and ``to_json`` filters change the format of your variable values. Jinja2 includes many `built-in filters <http://jinja.pocoo.org/docs/templates/#builtin-filters>`_ and Ansible supplies many more filters. To find more examples of filters, see :ref:`playbooks_filters`.
 
 .. _setting_variables:
 
 Where to set variables
 ======================
 
-You can set variables in a variety of places, including in inventory, in playbooks, in re-usable files, in roles, and at the command line. Ansible loads every possible variable it finds, then chooses the variable to apply based on :ref:`variable precedence rules <ansible_variable_precedence>`.
+You can define variables in a variety of places, such as in inventory, in playbooks, in reusable files, in roles, and at the command line. Ansible loads every possible variable it finds, then chooses the variable to apply based on :ref:`variable precedence rules <ansible_variable_precedence>`.
 
 .. _variables_in_inventory:
 
-Setting variables in inventory
+Defining variables in inventory
-------------------------------
+-------------------------------
 
-You can set different variables for each individual host, or set shared variables for a group of hosts in your inventory. For example, if all machines in the ``[Boston]`` group use 'boston.ntp.example.com' as an NTP server, you can set a group variable. The :ref:`intro_inventory` page has details on setting :ref:`host variables <host_variables>` and :ref:`group variables <group_variables>` in inventory.
+You can define different variables for each individual host, or set shared variables for a group of hosts in your inventory. For example, if all machines in the ``[Boston]`` group use 'boston.ntp.example.com' as an NTP server, you can set a group variable. The :ref:`intro_inventory` page has details on setting :ref:`host variables <host_variables>` and :ref:`group variables <group_variables>` in inventory.
 
 .. _playbook_variables:
 
-Setting variables in a playbook
+Defining variables in a playbook
--------------------------------
+--------------------------------
 
 You can define variables directly in a playbook::
 
@@ -198,17 +213,17 @@ You can define variables directly in a playbook::
      vars:
        http_port: 80
 
-When you set variables in a playbook, they are visible to anyone who runs that playbook. This is especially useful if you share playbooks widely.
+When you define variables in a playbook, they are visible to anyone who runs that playbook. This is especially useful if you share playbooks widely.
 
 .. _included_variables:
 .. _variable_file_separation_details:
 
-Setting variables in included files and roles
+Defining variables in included files and roles
----------------------------------------------
+----------------------------------------------
 
-You can set variables in re-usable variables files and/or in re-usable roles. See :ref:`playbooks_reuse` for more details.
+You can define variables in reusable variables files and/or in reusable roles. When you define variables in reusable variable files, the sensitive variables are separated from playbooks. This separation enables you to store your playbooks in a source control software and even share the playbooks, without the risk of exposing passwords or other sensitive and personal data. For information about creating reusable files and roles, see :ref:`playbooks_reuse`.
 
-Setting variables in included variables files lets you separate sensitive variables from playbooks, so you can keep your playbooks under source control and even share them without exposing passwords or other private information. You can do this by using an external variables file, or files, just like this::
+The following example shows how you can define variables in external files::
 
     ---
 
@@ -224,7 +239,7 @@ Setting variables in included variables files lets you separate sensitive variab
       - name: this is just a placeholder
         command: /bin/echo foo
 
-The contents of each variables file is a simple YAML dictionary, like this::
+The contents of each variables file is a simple YAML dictionary. For example::
 
     ---
     # in the above example, this would be vars/external_vars.yml
@@ -232,19 +247,19 @@ The contents of each variables file is a simple YAML dictionary, like this::
     password: magic
 
 .. note::
-   You can keep per-host and per-group variables in similar files, see :ref:`splitting_out_vars`.
+   You can keep per-host and per-group variables in similar files. To learn about organizing your variables, see :ref:`splitting_out_vars`.
 
 .. _passing_variables_on_the_command_line:
 
-Setting variables at runtime
+Defining variables at runtime
-----------------------------
+-----------------------------
 
-You can set variables when you run your playbook by passing variables at the command line using the ``--extra-vars`` (or ``-e``) argument. You can also request user input with a ``vars_prompt`` (see :ref:`playbooks_prompts`). When you pass variables at the command line, use a single quoted string (containing one or more variables) in one of the formats below.
+You can define variables when you run your playbook by passing variables at the command line using the ``--extra-vars`` (or ``-e``) argument. You can also request user input with a ``vars_prompt`` (see :ref:`playbooks_prompts`). When you pass variables at the command line, use a single quoted string, that contains one or more variables, in one of the formats below.
 
 key=value format
 ^^^^^^^^^^^^^^^^
 
-Values passed in using the ``key=value`` syntax are interpreted as strings. Use the JSON format if you need to pass non-string values (Booleans, integers, floats, lists, and so on).
+Values passed in using the ``key=value`` syntax are interpreted as strings. Use the JSON format if you need to pass non-string values such as Booleans, integers, floats, lists, and so on.
 
 .. code-block:: text
 
@@ -281,9 +296,12 @@ Variable precedence: Where should I put a variable?
 
 You can set multiple variables with the same name in many different places. When you do this, Ansible loads every possible variable it finds, then chooses the variable to apply based on variable precedence. In other words, the different variables will override each other in a certain order.
 
-Ansible configuration, command-line options, and playbook keywords can also affect Ansible behavior. In general, variables take precedence, so that host-specific settings can override more general settings. For examples and more details on the precedence of these various settings, see :ref:`general_precedence_rules`.
+Some behavioral parameters can be set in variables and also in Ansible configuration, as command-line options, and using playbook keywords. In general, if the same parameter is set by a variable and by another method, the variable takes precedence, so that host-specific settings can override the more general settings. For examples and more details on the precedence of these various settings, see :ref:`general_precedence_rules`.
+
+Teams and projects that agree on guidelines for defining variables (where to define certain types of variables) usually avoid variable precedence concerns. We suggest that you define each variable in one place: figure out where to define a variable, and keep it simple. However, this is not always possible.
 
-Teams and projects that agree on guidelines for defining variables (where to define certain types of variables) usually avoid variable precedence concerns. We suggest you define each variable in one place: figure out where to define a variable, and keep it simple. However, this is not always possible.
+Understanding variable precedence
+---------------------------------
 
 Ansible does apply variable precedence, and you might have a use for it. Here is the order of precedence from least to greatest (the last listed variables winning prioritization):
 
@@ -310,9 +328,9 @@ Ansible does apply variable precedence, and you might have a use for it. Here is
   #. include params
   #. extra vars (for example, ``-e "user=my_user"``)(always win precedence)
 
-In general, Ansible gives higher precedence to variables that were defined more recently, more actively, and with more explicit scope. Variables in the the defaults folder inside a role are easily overridden. Anything in the vars directory of the role overrides previous versions of that variable in the namespace. Host and/or inventory variables override role defaults, but do not override explicit includes like the vars directory or an ``include_vars`` task.
+In general, Ansible gives higher precedence to variables that were defined more recently, more actively, and with more explicit scope. Variables in the the defaults folder inside a role are easily overridden. Anything in the vars directory of the role overrides previous versions of that variable in the namespace. Host and/or inventory variables override role defaults, but explicit includes such as the vars directory or an ``include_vars`` task override inventory variables.
 
-Ansible merges different variables set in inventory so that more specific settings override more generic settings. For example, ``ansible_ssh_user`` specified as a group_var has a higher precedence than ``ansible_user`` specified as a host_var. See :ref:`how_we_merge` for more details on the precedence of variables set in inventory.
+Ansible merges different variables set in inventory so that more specific settings override more generic settings. For example, ``ansible_ssh_user`` specified as a group_var has a higher precedence than ``ansible_user`` specified as a host_var. For details about the precedence of variables set in inventory, see :ref:`how_we_merge`.
 
 .. rubric:: Footnotes
 
@@ -338,7 +356,7 @@ You can decide where to set a variable based on the scope you want that value to
  * Play: each play and contained structures, vars entries (vars; vars_files; vars_prompt), role defaults and vars.
  * Host: variables directly associated to a host, like inventory, include_vars, facts or registered task outputs
 
-Inside a template you automatically have access to all variables that are in scope for a host, plus any registered variables, facts, and magic variables.
+Inside a template, you automatically have access to all variables that are in scope for a host, plus any registered variables, facts, and magic variables.
 
 .. _variable_examples: