try to clarify run_once and forall! (ansible#37754)

* try to clarify run_once and forall!

* fixed hidden tls middle man

* make when note

* Minor edit

* Typo fix

docs/docsite/keyword_desc.yml

@@ -57,7 +57,7 @@ register: Name of variable that will contain task status and module return data.
 rescue: List of tasks in a :term:`block` that run if there is a task error in the main :term:`block` list.
 retries: "Number of retries before giving up in a :term:`until` loop. This setting is only used in combination with :term:`until`."
 roles: List of roles to be imported into the play
-run_once: Boolean that will bypass the host loop, forcing the task to execute on the first host available and will also apply any facts to all active hosts.
+run_once: Boolean that will bypass the host loop, forcing the task to attempt to execute on the first host available and afterwards apply any results and facts to all active hosts in the same batch.
 serial: |
     Explicitly define how Ansible batches the execution of the current play on the play's target
 

docs/docsite/rst/user_guide/playbooks_delegation.rst

@@ -203,8 +203,8 @@ This way you can lookup `hostvars['dbhost1']['default_ipv4']['address']` even th
 Run Once
 ````````
 
-In some cases there may be a need to only run a task one time and only on one host. This can be achieved
-by configuring "run_once" on a task::
+In some cases there may be a need to only run a task one time for a batch of hosts.
+This can be achieved by configuring "run_once" on a task::
 
     ---
     # ...
@@ -218,25 +218,31 @@ by configuring "run_once" on a task::
 
         # ...
 
-This can be optionally paired with "delegate_to" to specify an individual host to execute on::
+This directive forces the task to attempt execution on the first host in the current batch and then applies all results and facts to all the hosts in the same batch.
+
+This approach is similar to applying a conditional to a task such as::
 
         - command: /opt/application/upgrade_db.py
-          run_once: true
-          delegate_to: web01.example.org
+          when: inventory_hostname == webservers[0]
 
-When "run_once" is not used with "delegate_to" it will execute on the first host, as defined by inventory,
-in the group(s) of hosts targeted by the play - e.g. webservers[0] if the play targeted "hosts: webservers".
+But the results are applied to all the hosts.
 
-This approach is similar to applying a conditional to a task such as::
+Like most tasks, this can be optionally paired with "delegate_to" to specify an individual host to execute on::
 
         - command: /opt/application/upgrade_db.py
-          when: inventory_hostname == webservers[0]
+          run_once: true
+          delegate_to: web01.example.org
+
+As always with delegation, the action will be executed on the delegated host, but the information is still that of the original host in the task.
 
 .. note::
      When used together with "serial", tasks marked as "run_once" will be run on one host in *each* serial batch.
      If it's crucial that the task is run only once regardless of "serial" mode, use
      :code:`when: inventory_hostname == ansible_play_hosts[0]` construct.
 
+.. note::
+    Any conditional (i.e `when:`) will use the variables of the 'first host' to decide if the task runs or not, no other hosts will be tested.
+
 .. _local_playbooks:
 
 Local Playbooks