Docs: Relabel SEO guide as explanation (Diátaxis)

docs/user/glossary.rst

@@ -16,7 +16,7 @@ so that you have a reference for how we're using them.
 
    discoverability
       A documentation page is said to be *discoverable* when a user that needs it can find it through various methods:
-      Navigation, searching and cross-references from other pages are the
+      Navigation, in-docs searching, cross-references from other pages, and search engine optimization are the most typical ways of making content *discoverable*.
 
    Docs as Code
       A term used to describe the workflow of keeping documentation in a Git repository,

docs/user/guides/technical-docs-seo-guide.rst

@@ -14,6 +14,10 @@ While you optimize your docs to make them more friendly for search engine spider
 it's important to keep in mind that your ultimate goal is to make your docs
 more :term:`discoverable <discoverability>` for your users.
 
+By following :ref:`best practices for SEO <guides/technical-docs-seo-guide:Best practices for documentation SEO>`,
+you can ensure that when a user types a question into a search engine,
+they can get the answers from your documentation in the search results.
+
 .. seealso::
 
    This guide isn't meant to be your only resource on SEO,
@@ -81,18 +85,25 @@ which we'll discuss shortly,
 the most important thing is making sure the spider can follow links on your site
 and get to all your pages.
 
-Avoid orphan pages ✅️
-~~~~~~~~~~~~~~~~~~~~~~
+Avoid unlinked pages ✅️
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+When building your documentation,
+you should ensure that pages aren't *unlinked* or *orphaned*,
+meaning that no other pages or navigation have a link to them.
 
-Sphinx calls pages that don't have links to them "orphans"
-and will throw a warning while building documentation that contains an orphan
-unless the warning is silenced with the :ref:`orphan directive <sphinx:metadata>`:
+Search engine crawlers will not discover pages that aren't referenced.
+
+.. TODO: Create a "generic" tab?
 
 .. tabs::
 
    .. tab:: Sphinx
 
-        Sphinx will warn you when a page isn't referenced by the remaining documentation.
+        Sphinx calls pages that don't have links to them "orphans"
+        and will throw a warning while building documentation that contains an orphan
+        unless the warning is silenced with the :ref:`orphan directive <sphinx:metadata>`.
+
         We recommend failing your builds whenever Sphinx warns you,
         using the ``fail_on_warnings`` option in :ref:`.readthedocs.yaml <config-file/v2:sphinx>`.
 
@@ -110,10 +121,9 @@ unless the warning is silenced with the :ref:`orphan directive <sphinx:metadata>
    .. tab:: MkDocs
 
       MkDocs automatically includes all ``.md`` files in the main navigation 💯️.
-      So it does not need to report back about unreferenced files.
-      You have to go out of your way and install a plugin,
-      if you want to hide files from the navigation.
-      If you do want to scan your documentation for unreferenced files and images,
+      This makes sure that all files are discoverable by default,
+      however there are configurations that allow for unlinked files in various ways.
+      If you want to scan your documentation for unreferenced files and images,
       a plugin like `mkdocs-unused-files`_ does the job.
 
 
@@ -132,6 +142,8 @@ make sure the rest of that page describes the content of the video.
 
 When using images, make sure to set the image alt text or set a caption on figures.
 
+.. TODO: Create a "generic" tab?
+
 .. tabs::
 
    .. tab:: Sphinx
@@ -149,13 +161,13 @@ When using images, make sure to set the image alt text or set a caption on figur
 
    .. tab:: MkDocs
 
-        The Markdown syntax fundamentally prescribes an alt text for images:
+        The Markdown syntax defines an alt text for images:
 
         .. code-block:: md
 
            ![Image alt text](https://dummyimage.com/600x400/){ width="300" }
 
-        If you want to use figures and captions,
+        Though HTML supports figures and captions,
         Markdown and MkDocs do not have a built-in feature.
         Instead,
         you can use markdown extensions such as `md-in-html`_ to allow the necessary HTML structures for including figures: