diff --git a/docs/references/keywords.rst b/docs/references/keywords.rst
index c26b9d497db..969d4dd588c 100644
--- a/docs/references/keywords.rst
+++ b/docs/references/keywords.rst
@@ -250,6 +250,12 @@ Keywords
     an ``.egg`` file.
 
 ``namespace_packages``
+
+    .. warning::
+        Deprecated in favor of native/implicit namespaces (:pep:`420`).
+        Check :doc:`the Python Packaging User Guide
+        <PyPUG:guides/packaging-namespace-packages>` for more information.
+
     A list of strings naming the project's "namespace packages".  A namespace
     package is a package that may be split across multiple project
     distributions.  For example, Zope 3's ``zope`` package is a namespace
diff --git a/docs/userguide/declarative_config.rst b/docs/userguide/declarative_config.rst
index 52379dbf1c6..2a65e6e3677 100644
--- a/docs/userguide/declarative_config.rst
+++ b/docs/userguide/declarative_config.rst
@@ -210,7 +210,7 @@ packages                 find:, find_namespace:, list-comma                   [#
 package_dir              dict
 package_data             section                                              [#opt-1]_
 exclude_package_data     section
-namespace_packages       list-comma
+namespace_packages       list-comma                                           [#opt-5]_
 py_modules               list-comma                            34.4.0
 data_files               section                              40.6.0          [#opt-4]_
 =======================  ===================================  =============== =========
@@ -243,6 +243,10 @@ data_files               section                              40.6.0          [#
 .. [#opt-4] ``data_files`` is deprecated and should be avoided.
    Please check :doc:`/userguide/datafiles` for more information.
 
+.. [#opt-5] ``namespace_packages`` is deprecated in favour of native/implicit
+   namespaces (:pep:`420`). Check :doc:`the Python Packaging User Guide
+   <PyPUG:guides/packaging-namespace-packages>` for more information.
+
 
 Compatibility with other tools
 ==============================
diff --git a/docs/userguide/keywords.rst b/docs/userguide/keywords.rst
index 5388ffea7f4..b1c9817e4cb 100644
--- a/docs/userguide/keywords.rst
+++ b/docs/userguide/keywords.rst
@@ -89,6 +89,8 @@ unless you need the associated ``setuptools`` feature.
     does not contain any code other than a namespace declaration.  See the
     section below on :ref:`Namespace Packages` for more information.
 
+    *Deprecated in favor of native/implicit namespaces* (:pep:`420`).
+
 ``test_suite``
     A string naming a ``unittest.TestCase`` subclass (or a package or module
     containing one or more of them, or a method of such a subclass), or naming
diff --git a/docs/userguide/pyproject_config.rst b/docs/userguide/pyproject_config.rst
index 47c4511ebb4..e20f4ab9004 100644
--- a/docs/userguide/pyproject_config.rst
+++ b/docs/userguide/pyproject_config.rst
@@ -94,7 +94,7 @@ Key                       Value Type (TOML)           Notes
 ``py-modules``            array                       See tip below
 ``packages``              array or ``find`` directive See tip below
 ``package-dir``           table/inline-table          Used when explicitly listing ``packages``
-``namespace-packages``    array                       Not necessary if you use :pep:`420`
+``namespace-packages``    array                       **Deprecated** - Use implicit namespaces instead (:pep:`420`)
 ``package-data``          table/inline-table          See :doc:`/userguide/datafiles`
 ``include-package-data``  boolean                     ``True`` by default
 ``exclude-package-data``  table/inline-table