update ansible.legacy docs (#76839)

* update ansible.legacy docs

* correct role description

* Update docs/docsite/rst/dev_guide/developing_locally.rst

* Update docs/docsite/rst/dev_guide/developing_locally.rst

docs/docsite/rst/dev_guide/developing_locally.rst

@@ -133,3 +133,10 @@ Ansible automatically loads all plugins from certain directories adjacent to you
 .. warning::
 
    Roles contained in collections cannot contain any plugins. All plugins in a collection must live in the collection ``plugins`` directory tree. All plugins in that tree are accessible to all roles in the collection. If you are developing new plugins, we recommend distributing them in :ref:`collections <developing_collections>`, not in roles.
+
+.. _ansible.legacy.custom:
+
+Using ``ansible.legacy`` to access custom versions of an ``ansible.builtin`` module
+===================================================================================
+
+If you need to override one of the ``ansible.builtin`` modules and are using FQCN, you need to use ``ansible.legacy`` as part of the fully-qualified collection name (FQCN). For example, if you had your own ``copy`` module, you would access it as ``ansible.legacy.copy``. See :ref:`using_ansible_legacy` for details on how to use custom modules with roles within a collection.

docs/docsite/rst/dev_guide/migrating_roles.rst

@@ -413,15 +413,4 @@ The following is an example RPM spec file that accomplishes this using this exam
 Using ``ansible.legacy`` to access local custom modules from collections-based roles
 =====================================================================================
 
-Some roles use :ref:`local custom modules <developing_locally>` that are not part of the role itself. When you move these roles into collections, they can no longer find those custom plugins. You can add the synthetic collection ``ansible.legacy`` to enable legacy behavior and find those custom plugins. Adding ``ansible.legacy`` configures your role to search the pre-collections default paths for modules and plugins.
-
-To enable a role hosted in a collection to find legacy custom modules and other plugins hosted locally:
-
-Edit the role's ``meta/main.yml`` and add the ``ansible.legacy`` collection to your collection-hosted role to enable the use of legacy custom modules and plugins for all tasks:
-
-.. code-block:: yaml
-
-   collections:
-     - ansible.legacy
-
-Alternatively, you can update the tasks directly by changing ``local_module_name`` to ``ansible.legacy.local_module_name``.
+Some roles within a collection use :ref:`local custom modules <developing_locally>` that are not part of the collection itself. If there is a conflict between the custom module short name and the collection module name, you need to specify which module your tasks call. You can update the tasks to change ``local_module_name`` to ``ansible.legacy.local_module_name`` to ensure you are using the custom module.