Docs: clarify that roles do not inherit collections set in a playbook (#66667)

Co-authored-by: Matt Davis <nitzmahone@users.noreply.github.com>
Co-authored-by: Sandra McCann <samccann@redhat.com>

docs/docsite/rst/user_guide/collections_using.rst

@@ -74,9 +74,31 @@ This works for roles or any type of plugin distributed within the collection:
          - debug:
              msg: '{{ lookup("my_namespace.my_collection.lookup1", 'param1')| my_namespace.my_collection.filter1 }}'
 
+Simplifying module names with the ``collections`` keyword
+=========================================================
 
-To avoid a lot of typing, you can use the ``collections`` keyword added in Ansible 2.8:
+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.
+
+Using ``collections`` in roles
+------------------------------
+
+Within a role, you can control which collections Ansible searches for the tasks inside the role using the ``collections`` keyword in the role's ``metadata/main.yml``. Ansible will use the collections list defined inside the role even if the playbook that calls the role defines different collections in a separate ``collections`` keyword entry. Roles defined inside a collection always implicitly search their own collection first, so you don't need to use the ``collections`` keyword to access modules, actions, or other roles contained in the same collection.
+
+.. code-block:: yaml
+
+   # myrole/metadata/main.yml
+   collections:
+     - my_namespace.first_collection
+     - my_namespace.second_collection
+     - other_namespace.other_collection
+
+Using ``collections`` in playbooks
+----------------------------------
+
+In a playbook, you can control the collections Ansible searches for modules and action plugins to execute. However, any roles you call in your playbook define their own collections search order; they do not inherit the calling playbook's settings. This is true even if the role does not define its own ``collections`` keyword.
 
 .. code-block:: yaml
 
@@ -93,8 +115,7 @@ To avoid a lot of typing, you can use the ``collections`` keyword added in Ansib
          - debug:
              msg: '{{ lookup("my_namespace.my_collection.lookup1", 'param1')| my_namespace.my_collection.filter1 }}'
 
-This keyword creates a 'search path' for non namespaced plugin references. It does not import roles or anything else.
-Notice that you still need the FQCN for non-action or module plugins.
+The ``collections`` keyword merely creates an ordered 'search path' for non-namespaced plugin and role references. It does not install content or otherwise change Ansible's behavior around the loading of plugins or roles. Note that an FQCN is still required for non-action or module plugins (e.g., lookups, filters, tests).
 
 .. seealso::