diff --git a/Doc/documenting/markup.rst b/Doc/documenting/markup.rst
index e48bb01f724..b4421cb23b0 100644
--- a/Doc/documenting/markup.rst
+++ b/Doc/documenting/markup.rst
@@ -205,6 +205,9 @@ The directives are:
 
          Set name of the decorated function to *name*.
 
+   There is no ``deco`` role to link to a decorator that is marked up with
+   this directive; rather, use the ``:func:`` role.
+
 .. describe:: class
 
    Describes a class.  The signature can include parentheses with parameters
@@ -226,6 +229,8 @@ The directives are:
 
    Same as ``decorator``, but for decorators that are methods.
 
+   Refer to a decorator method using the ``:meth:`` role.
+
 .. describe:: opcode
 
    Describes a Python :term:`bytecode` instruction.