From d6063b7457086a2ed04899c47d1fc6ee4d654de9 Mon Sep 17 00:00:00 2001
From: Sandra McCann <samccann@redhat.com>
Date: Thu, 24 Sep 2020 10:45:11 -0400
Subject: [PATCH] clarify FQCN use for playbooks (#71816)

* clarify FQCN use

* Apply suggestions from code review

Co-authored-by: Alicia Cozine <879121+acozine@users.noreply.github.com>

Co-authored-by: Alicia Cozine <879121+acozine@users.noreply.github.com>
---
 .../rst/user_guide/collections_using.rst      |  2 +-
 .../rst/user_guide/playbooks_intro.rst        | 24 +++++++++++--------
 2 files changed, 15 insertions(+), 11 deletions(-)

diff --git a/docs/docsite/rst/user_guide/collections_using.rst b/docs/docsite/rst/user_guide/collections_using.rst
index a9530a9e1d0..78ae2b61cac 100644
--- a/docs/docsite/rst/user_guide/collections_using.rst
+++ b/docs/docsite/rst/user_guide/collections_using.rst
@@ -274,7 +274,7 @@ Simplifying module names with the ``collections`` keyword
 The ``collections`` keyword lets you define a list of collections that your role or playbook should search for unqualified module and action names. So you can use the ``collections`` keyword, then simply refer to modules and action plugins by their short-form names throughout that role or playbook.
 
 .. warning::
-   If your playbook uses both the ``collections`` keyword and one or more roles, the roles do not inherit the collections set by the playbook. See below for details.
+   If your playbook uses both the ``collections`` keyword and one or more roles, the roles do not inherit the collections set by the playbook. This is one of the reasons we recommend you always use FQCN. See below for roles details.
 
 Using ``collections`` in roles
 ------------------------------
diff --git a/docs/docsite/rst/user_guide/playbooks_intro.rst b/docs/docsite/rst/user_guide/playbooks_intro.rst
index 24037b3ed85..10334076fb5 100644
--- a/docs/docsite/rst/user_guide/playbooks_intro.rst
+++ b/docs/docsite/rst/user_guide/playbooks_intro.rst
@@ -33,34 +33,38 @@ A playbook runs in order from top to bottom. Within each play, tasks also run in
 * the managed nodes to target, using a :ref:`pattern <intro_patterns>`
 * at least one task to execute
 
+.. note::
+
+	In Ansible 2.10 and later, we recommend you use the fully-qualified collection name in your playbooks to ensure the correct module is selected, because multiple collections can contain modules with the same name (for example, ``user``). See :ref:`collections_using_playbook`.
+
 In this example, the first play targets the web servers; the second play targets the database servers::
 
     ---
-    - name: update web servers
+    - name: Update web servers
       hosts: webservers
       remote_user: root
 
       tasks:
-      - name: ensure apache is at the latest version
-        yum:
+      - name: Ensure apache is at the latest version
+        ansible.builtin.yum:
           name: httpd
           state: latest
-      - name: write the apache config file
-        template:
+      - name: Write the apache config file
+        ansible.builtin.template:
           src: /srv/httpd.j2
           dest: /etc/httpd.conf
 
-    - name: update db servers
+    - name: Update db servers
       hosts: databases
       remote_user: root
 
       tasks:
-      - name: ensure postgresql is at the latest version
-        yum:
+      - name: Ensure postgresql is at the latest version
+        ansible.builtin.yum:
           name: postgresql
           state: latest
-      - name: ensure that postgresql is started
-        service:
+      - name: Ensure that postgresql is started
+        ansible.builtin.service:
           name: postgresql
           state: started