(DOCSP-22851): Update linking guidelines (#109)

* (DOCSP-22851): Add linking guidelines

* retry autobuilder

* formatting

* wording

* formatting

* cleanup

Author: jeff-allen-mongo

source/style-guide/style/links-and-cross-references.txt

@@ -4,135 +4,173 @@
 Links and Cross-References
 ==========================
 
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
 .. default-domain:: mongodb
 
 .. include:: /includes/styles/corrections.rst
 
-Use cross-references to:
-
-- Help users navigate content
-- Find content related to what they're currently viewing.
-
-You can add hyperlinks to cross-references.
-
-.. note::
+Documentation writers use links to direct users to related material
+outside of the current page or section. Links may be:
 
-   {+Rst+} refers to text that points to other sections in the current document or in another document, or to other documents as
-   :sphinx-rst:`cross-references </roles.html#cross-referencing-syntax>`. Cross-references can include hyperlinks. You would use an {+rst+} role to format add a hyperlink to a cross-reference.
-   {+Rst+} refers to hyperlinks to other specific URLs as
-   :sphinx-rst:`links </basics.html#hyperlinks>`. This document uses cross-reference and link somewhat interchangeably.
+- Inline textual references to different sections. For example:
 
--  When you refer to content within the same article or section, such
-   as tables, figures, examples, or a subsection, create a simple
-   textual cross-reference. If the referenced copy falls much further
-   down the page, link to that content.
+  "Partial indexes include more details about indexed documents compared
+  to :manual:`Sparse Indexes </core/index-sparse/>`."
 
--  When you refer to other content, whether created by MongoDB or
-   outside of MongoDB, provide a link to that content. Verify that the
-   link works and that the content is current. Periodically check the
-   link and content. If you link to Uncyclopedia or any other site that
-   uses history, link to a specific revision of that page or content.
+- Explicit references to different sections. For example:
 
-   .. example::
+  "To learn more about aggregation pipelines, see:
 
-      .. code-block:: rst
+  - :ref:`aggregation-expression-operators`
+  - :ref:`aggregation-pipeline-operator-reference`
+  - `Practical MongoDB Aggregations
+    <https://www.practical-mongodb-aggregations.com>`__"
 
-         Timestamp in the number of seconds that have elapsed since the
-         :wikipedia:`UNIX epoch </Unix_time?oldid=828172017>` when
-         someone last updated this setting.
+- Explicit hyperlinks to specific URLs. For example, a link to a GitHub
+  repository.
 
-.. _sg-link-text:
-
-Link and Cross-Reference Text
------------------------------
+Best Practices
+--------------
 
 Use the following guidelines to create clear and specific
-cross-references. For examples, see the table at the end of
-the topic.
-
-- Begin a cross-reference sentence with the purpose or benefit of the
-  cross-reference (such as more information or examples). Such context
-  helps users decide whether to follow the reference.
-
-- Use *To learn more about* rather than *For more information on*.
-
-- Use *preceding* and *following* to locate information in an article
-  or topic. Don't use *above*, *below*, *earlier*, or *later*.
-
-- Ensure that the cross-refernce or link text sufficiently describes
-  the target content.
-
-  - For links at the end of an article or topic that point to related
-    information or to a next step, use the title of or a heading in the
-    target content as the link text.
-
-  - When links are inline, use about three or four words of existing
-    text as the link text. Choose words that best describe the
-    target content.
-
-  - If existing text can't sufficiently describe the target
-    content, create a cross-reference sentence for the link. For the
-    link text, use the title of or a heading in the target
-    content, if possible. Avoid providing an actual URL, unless you
-    think that having the URL is helpful for the user.
-
-  - Don't provide links from ambiguous phrases such as *Click here* or
-    *More information*.
-
-  .. note::
-
-     - Provide links *inline* only when it's necessary or helpful for
-       the user to follow the link to understand the current topic or
-       complete the task.
-
-     - Provide links to related but not essential information, and to
-       next steps, at the end of the article or section, preferrably
-       under a ``.. seealso::`` directive.
-
-- If a link points to a location other than the current site (for
-  example, out of the Support website or away from
-  www.mongodb.com/docs), provide context that describes the location.
-
-.. _sg-link-formatting:
-
-Link and Cross-Reference Formatting
------------------------------------
-
-- Don't code a link to open in a new tab or window. Users can choose
-  whether they want open a link in a new tab or window.
-
-- If your article or topic has multiple subheadings, provide a TOC
-  (jump list) at the beginning of the article or topic, after an
-  introduction. Use the heading text as the link text, and typically
-  link only to the top-level headings in the article or topic.
-
-  .. note::
-
-     Don't create a TOC within the article manually. Add the
-     ``.. contents::`` directive to generate a TOC.
-
-- Don't use quotation marks around link text.
-
-- Create and format links using either:
-
-  - custom roles (like ``:rfc:``, ``:manual:`` or ``:gh:``), or
-  - standard {+rst+}
-    :sphinx-rst:`external links </basics.html#external-links>` ending
-    with two underscores instead of one.
-
-    .. note::
-
-       The documentation rendering engine expects links to be unique if
-       they end with only one underscore. If you create two links to
-       the same URL with only one underscore, the engine returns a
-       build error. If you end the link with two underscores, the
-       engine creates modifies subsequent URLs to prevent this build
-       error.
-
-- Test links to ensure that they're live and that they point to
-  the correct target.
-
-- Don't link to information more than once in an article or topic.
+links and cross-references.
+
+Link with Care
+~~~~~~~~~~~~~~
+
+Before you link to a separate page or section, consider whether that
+link actually aids user understanding. To minimize reader disruption,
+aim to keep users on the page they're currently reading as much as
+possible. If you are considering adding a link, see if the content would
+be better served by providing a brief definition or key concept on the
+page the reader is currently reading, rather than making the user do
+additional navigation on their own.
+
+Be aware that providing a brief definition or attempting to explain a
+concept on the current page may introduce maintenance issues. If the
+behavior of the topic we're describing changes, it may become more
+difficult to track down each place that topic is mentioned and know what
+needs to be updated. When possible, use an include to single-source
+content and reduce future maintenance.
+
+Consider Link Placement
+~~~~~~~~~~~~~~~~~~~~~~~
+
+Generally, an explicit reference at the end of a page or section is less
+disruptive than an inline textual reference, especially when there are
+several inline references in succession. If you introduce a few concepts
+you'd like to provide links to, consider grouping links to concepts into
+either:
+
+- A "Learn More" section with a consolidated list of links.
+- A ``..seealso`` directive at the end of the section.
+
+By using one of these approaches, users who just want to complete a task
+aren't distracted by additional links, and users who want to learn more
+about MongoDB concepts can click through and explore the linked content.
+
+Avoid Inline References in Tutorials
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Avoid inline textual references in tutorials or stepped procedures. If
+users follow inline references while in the middle of a procedure, they
+may have difficulty navigating back and reorienting themselves with
+their current step.
+
+Additionally, avoid stacking multiple admonitions directly after one
+another, as these can be distracting for users. To avoid stacking
+admonitions, consider grouping supplemental information from admonitions
+into a dedicated section.
+
+Inline textual references may be appropriate for more reference-heavy
+pages. Admonitions can potentially reduce scannability of tables and
+options lists, and should therefore be avoided in those contexts
+whenever possible.
+
+Minimize Repeated Links
+~~~~~~~~~~~~~~~~~~~~~~~
+
+Don't link to the same target multiple times in the same section.
+
+You may link to the same target multiple times on the same page, but
+think carefully about whether it's absolutely necessary. For example, if
+a page is particularly long and contains many sections, then it might be
+helpful to link to a target an additional time or two. Users may
+immediately navigate to a section far down on a page and miss the
+initial reference.
+
+When providing repeated links, ensure that the same style is used each
+time a link is used. Consider whether a plaintext link or a
+monospace link is appropriate. Plaintext links may be less visually
+distracting than monospace links because they do not have the
+surrounding block.
+
+Make Link Text Clear
+~~~~~~~~~~~~~~~~~~~~
+
+Strive to be clear about where exactly a link will take a reader. Follow
+these guidelines for link text to ensure readers know the purpose of a
+link and where it will take them:
+
+- Use descriptive text indicating where the URL will take the reader.
+- Avoid jargon in link text. Using technical terms as needed, such as
+  the name of an operator or method, is appropriate.
+- Use normal English words as opposed to URLs.
+- If a link will take a user away from the MongoDB documentation, such
+  as to GitHub or Uncyclopedia, make the target site clear in the link
+  text.
+- Avoid "Click here." It's bad for search engine optimization and
+  doesn't adequately describe the target.
+
+Link text should begin with the purpose of the cross-reference. For
+example:
+
+- "To learn more, see..."
+- "To see examples..."
+- "For more information, see..."
+
+The linked text should correspond to the title of the page or section
+you are linking to. For example, consider the following sentence which
+provides a cross-reference:
+
+  To learn more, see the guide on Finding Multiple Documents in the
+  Node.js Driver Documentation.
+
+The linked text should correspond to the title of the guide. In this
+example, the title of the guide is "Finding Multiple Documents". The
+complete link sentence should look like this:
+
+  To learn more, see the guide on :driver:`Finding Multiple Documents
+  </node/current/usage-examples/find/>` in the Node.js Driver
+  Documentation.
+
+Use MongoDB-Domain Links When Possible
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Link to the MongoDB domain whenever possible instead of directing users
+to external domains. Some topics described in our documentation are also
+covered by other products' documentation, external tutorials, or
+Uncyclopedia. By keeping users in the MongoDB domain, we ensure that we are
+in full control of the content presented, and maintain trust with users.
+
+Directing users outside of the MongoDB domain is acceptable when it is
+critical to provide additional context on a topic and we do not have
+sufficient context in our documentation to cover user needs.
+
+Use ``:ref:`` Links Instead of ``:doc:`` Links
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When linking to content within the MongoDB documentation, use ``:ref:``
+links instead of ``:doc:`` links. ``:ref:`` links make maintenance
+easier in the event that a section is refactored or consolidated into a
+new page because we can simply bring the reference along with the
+paragraph or section we're pointing to. When using ``:doc:`` links, a
+refactor can potentially break links if the page is renamed or removed.
 
 .. _sg-link-examples:
 
@@ -165,7 +203,7 @@ Link and Cross-Reference Examples
        :mdbdrivers:`MongoDB Drivers site </>`.
      - The most current versions of all drivers are located on the
        MongoDB Developer Docs site:
-       https://www.mongodb.com/docs/drivers/.
+       https://docs.mongodb.com/ecosystem/drivers/.
 
    * - You can obtain the API key by logging in to
        :mdbcloud:`Atlas </>` and clicking the