Update documentation/style-guide.rst

Co-authored-by: Carol Willing <[email protected]>

Author: nedbat

documentation/style-guide.rst

@@ -134,23 +134,22 @@ 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 used only if they help the reader.
 
-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, such as a section or paragraph. 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.
+Generally, a link should be provided for the first use of a term in a unit,
+such as a section or paragraph. This is not a hard and fast rule.  Sometimes
+the second mention is more appropriate for a link.  Some units are long enough
+to have a few repeated links.  Use judgement to decide when a link will 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.
 
-Do not use links in section headers.  They interrupt the flow, and the term
-will be mentioned in the paragraph text so can be linked from there.
+Do not use links in section headers.  They distract from the title of the
+section.  The term will be mentioned in the paragraph text and can be linked
+from there.
 
 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