Add section to the docs guiding the user on how to migrate (relying on the _legacy module as a guide because it's so easy to read).

Author: jaraco

CHANGES.rst

@@ -3,7 +3,9 @@ v5.3.0
 
 * #80: Now raise a ``DeprecationWarning`` for all legacy
   functions. Instead, users should rely on the ``files()``
-  API introduced in importlib_resources 1.3.
+  API introduced in importlib_resources 1.3. See
+  `Migrating from Legacy <https://importlib-resources.readthedocs.io/en/latest/using.html#migrating-from-legacy>`_
+  for guidance on avoiding the deprecated functions.
 
 v5.2.3
 ======

docs/using.rst

@@ -163,6 +163,21 @@ manager.
 Both relative and absolute paths work for Python 3.7 and newer.
 
 
+Migrating from Legacy
+=====================
+
+Starting with Python 3.9 and ``importlib_resources`` 1.4, this package
+introduced the ``files()`` API, to be preferred over the legacy API,
+i.e. the functions ``open_binary``, ``open_text``, ``path``,
+``contents``, ``read_text``, ``read_binary``, and ``is_resource``.
+
+To port to the ``files()`` API, refer to the
+`_legacy module <https://github.com/python/importlib_resources/blob/66ea2dc7eb12b1be2322b7ad002cefb12d364dff/importlib_resources/_legacy.py>`_
+to see simple wrappers that enable drop-in replacement based on the
+preferred API, and either copy those or adapt the usage to utilize the
+``files`` and ``Traversable`` interfaces directly.
+
+
 Extending
 =========