Avoid over-linking

Author: nedbat

Diff for: documentation/markup.rst

@@ -30,6 +30,7 @@ external links          ```Link text <https://example.com>`_``      :ref:`hyperl
 roles w/ custom text    ``:role:`custom text <target>```            :ref:`roles`
 roles w/ only last part ``:role:`~hidden.hidden.visible```          :ref:`roles`
 roles w/o link          ``:role:`!target```                         :ref:`roles`
+roles w/o link, short   ``:role:`~!hidden.hidden.visible```         :ref:`roles`
 issues                  ``:gh:`ID```, ``:issue:`ID```               :ref:`roles`
 CPython source          ``:source:`PATH```                          :ref:`roles`
 comments                ``.. a comment``                            :ref:`comments`

Diff for: documentation/style-guide.rst

@@ -124,11 +124,37 @@ explanation.
   provide context, make connections between topics, and discuss alternative
   opinions. There is no section dedicated to explanations but these can be
   found throughout Python's documentation, for example the
-  :ref:`python:unicode-howto`
+  :ref:`python:unicode-howto`.
 
 Please consult the `Diátaxis <https://diataxis.fr/>`_ guide for more
 detail.
 
+Links
+=====
+
+Linking words to more information about those words is a powerful tool for
+helping people navigate documentation, but links can be over-used.
+
+Links should be provided only if they help the user.  If a link will not help
+the user, do not create a link.  You may need to suppress a link that Sphinx
+would have created automatically.
+
+Generally, a link should be provided for the first use of a term in a unit This
+is not a hard and fast rule.  Sometimes the second mention is a more
+appropriate jumping off point.  Some units are long enough to have a few
+repeated links.  Use judgement to decide if a link would help the reader.
+
+Do not use a link when the link would point to the current unit.  It's natural
+to use the name of a function in the documentation for the function, but a link
+on that function name that simply reloads the section the user is already
+reading is useless and distracting.
+
+Sphinx provides ways to automatically add links to references, and a way to
+suppress the link.  Using roles like ``:func:`map``` will link to the
+documentation for ``map``.  You can suppress the link while keeping the
+semantic presentation of the function name by adding an exclamation point
+prefix: ``:func:`!map```.
+
 Affirmative tone
 ================