diff --git a/doc/devel/api_changes.rst b/doc/devel/api_changes.rst
index 09709b0ec580..8b947ee946a7 100644
--- a/doc/devel/api_changes.rst
+++ b/doc/devel/api_changes.rst
@@ -256,3 +256,8 @@ To do so, add a note to the docstring ::
 
 You find several examples for good descriptions if you search the codebase for
 ``.. admonition:: Discouraged``.
+
+Additionally, if a whole function is discouraged, prefix the summary line with
+``[*Discouraged*]`` so that it renders in the API overview like this
+
+    [*Discouraged*] Return the XAxis instance.