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

* Transform the guide into an explanation with best practices, use Sphinx and MkDocs examples in tabs * Apply suggestions from @ericholscher's code review Co-authored-by: Eric Holscher <[email protected]> * Re-add motivational text with a reference to the best practices.. but can't be **bold** because reST * Finish the sentence * General intro to unlinked pages * Add TODO items * Apply suggestions from @ericholscher's code review Co-authored-by: Eric Holscher <[email protected]> --------- Co-authored-by: Eric Holscher <[email protected]>
readthedocs · Feb 10, 2023 · 83a294e · 83a294e
1 parent 2b720ee
commit 83a294e
Show file tree

Hide file tree

Showing 4 changed files with 108 additions and 59 deletions.
diff --git a/docs/user/glossary.rst b/docs/user/glossary.rst
@@ -14,6 +14,10 @@ so that you have a reference for how we're using them.
       Projects have a *default version*, usually the latest stable version of a project.
       The *default version* is the URL that is redirected to when a users loads the `/` URL for your project.
 
+   discoverability
+      A documentation page is said to be *discoverable* when a user that needs it can find it through various methods:
+      Navigation, search, and links from other pages 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,
       along with source code.

diff --git a/docs/user/guides/administrators.rst b/docs/user/guides/administrators.rst
@@ -16,7 +16,6 @@ have a look at our :doc:`/tutorial/index`.
    Connect your Read the Docs account to your Git repository <connecting-git-account>
    Manage Custom Domains <custom-domains>
    Enable Canonical URLs <canonical-urls>
-   technical-docs-seo-guide
    Use traffic analytics </analytics>
    manage-translations-sphinx
    hiding-a-version

diff --git a/docs/user/guides/technical-docs-seo-guide.rst b/docs/user/guides/technical-docs-seo-guide.rst
@@ -1,36 +1,29 @@
-Technical Documentation Search Engine Optimization (SEO) Guide
-==============================================================
+Search Engine Optimization (SEO) for documentation projects
+===========================================================
 
 .. meta::
     :description lang=en:
-        Looking to optimize your Sphinx documentation for search engines?
+        Looking to optimize your documentation project for search engines?
         This SEO guide will help your docs be better understood by both people and crawlers
         as well as help you rank higher in search engine results.
 
+This article explains how documentation can be optimized to appear in search results,
+ultimately increasing traffic to your docs.
 
-This guide will help you optimize your documentation for search engines
-with the goal of increasing traffic to your docs.
-While you optimize your docs to make them more crawler friendly for search engine spiders,
+While you optimize your docs to make them more friendly for search engine spiders/crawlers,
 it's important to keep in mind that your ultimate goal is to make your docs
-more discoverable for your users.
-**You're trying to make sure that when a user types a question into a search engine
-that is answerable by your documentation, that your docs appear in the results.**
+more :term:`discoverable <discoverability>` for your users.
 
-This guide isn't meant to be your only resource on SEO,
-and there's a lot of SEO topics not covered here.
-For additional reading, please see the
-:ref:`external resources <guides/technical-docs-seo-guide:External resources>` section.
+By following :ref:`our 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.
 
-While many of the topics here apply to all forms of technical documentation,
-this guide will focus on Sphinx, which is the most common
-documentation authoring tool on Read the Docs,
-as well as improvements provided by Read the Docs itself.
+.. seealso::
 
-
-.. contents:: Table of contents
-   :local:
-   :backlinks: none
-   :depth: 3
+   This guide isn't meant to be your only resource on SEO,
+   and there's a lot of SEO topics not covered here.
+   For additional reading, please see the
+   :ref:`external resources <guides/technical-docs-seo-guide:External resources>` section.
 
 
 SEO Basics
@@ -80,8 +73,8 @@ generates static HTML and the performance is typically decent
 relative to most of the internet.
 
 
-Optimizing your docs for search engine spiders
-----------------------------------------------
+Best practices for documentation SEO
+------------------------------------
 
 Once a crawler or spider finds your site, it will follow links and redirects
 in an attempt to find any and all pages on your site.
@@ -92,30 +85,53 @@ 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 ✅️
+~~~~~~~~~~~~~~~~~~~~~~~~
 
-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>`:
+When building your documentation,
+you should ensure that pages aren't *unlinked*,
+meaning that no other pages or navigation have a link to them.
 
-::
+Search engine crawlers will not discover pages that aren't linked from somewhere else on your site.
 
-    $ make html
-    sphinx-build -b html -d _build/doctrees . _build/html
-    Running Sphinx v1.8.5
-    ...
-    checking consistency... /path/to/file.rst: WARNING: document isn't included in any toctree
-    done
-    ...
-    build finished with problems, 1 warning.
+.. TODO: Create a "generic" tab?
 
-You can make all Sphinx warnings into errors during your build process
-by setting ``SPHINXOPTS = -W --keep-going`` in your Sphinx Makefile.
+.. tabs::
 
+   .. tab:: Sphinx
 
-Avoid uncrawlable content
-~~~~~~~~~~~~~~~~~~~~~~~~~
+        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>`.
+
+        Here is an example of a warning of an unreferenced page::
+
+            $ make html
+            sphinx-build -b html -d _build/doctrees . _build/html
+            Running Sphinx v1.8.5
+            ...
+            checking consistency... /path/to/file.rst: WARNING: document isn't included in any toctree
+            done
+            ...
+            build finished with problems, 1 warning.
+
+   .. tab:: MkDocs
+
+      MkDocs automatically includes all ``.md`` files in the main navigation 💯️.
+      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.
+
+
+.. _mkdocs-unused-files: https://github.com/wilhelmer/mkdocs-unused-files
+
+
+Avoid uncrawlable content ✅️
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 While typically this isn't a problem with technical documentation,
 try to avoid content that is "hidden" from search engines.
@@ -125,20 +141,49 @@ For example, if you do have a video in your docs,
 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.
-For Sphinx, the image and figure directives support this:
 
-.. sourcecode:: rst
+.. TODO: Create a "generic" tab?
+
+.. tabs::
+
+   .. tab:: Sphinx
 
-    .. image:: your-image.png
-        :alt: A description of this image
+        For Sphinx, the image and figure directives support both alt texts and captions:
 
-    .. figure:: your-image.png
+        .. code-block:: rst
 
-        A caption for this figure
+            .. image:: your-image.png
+                :alt: A description of this image
 
+            .. figure:: your-image.png
 
-Redirects
-~~~~~~~~~
+                A caption for this figure
+
+   .. tab:: MkDocs
+
+        The Markdown syntax defines an alt text for images:
+
+        .. code-block:: md
+
+           ![Image alt text](https://dummyimage.com/600x400/){ width="300" }
+
+        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:
+
+        .. code-block:: md
+
+           <figure markdown>
+              ![Image alt text](https://dummyimage.com/600x400/){ width="300" }
+              <figcaption>Image caption</figcaption>
+           </figure>
+
+.. _md-in-html: https://python-markdown.github.io/extensions/md_in_html/
+
+
+Redirects ✅️
+~~~~~~~~~~~~~
 
 Redirects tell search engines when content has moved.
 For example, if this guide moved from ``guides/technical-docs-seo-guide.html`` to ``guides/sphinx-seo-guide.html``,
@@ -152,8 +197,8 @@ that should cover all the different cases such as redirecting a certain page for
 or redirecting one version to another.
 
 
-Canonical URLs
-~~~~~~~~~~~~~~
+Canonical URLs ✅️
+~~~~~~~~~~~~~~~~~~
 
 Anytime very similar content is hosted at multiple URLs,
 it is pretty important to set a canonical URL.
@@ -167,8 +212,8 @@ under :guilabel:`Admin` > :guilabel:`Domains`
 in the Read the Docs dashboard.
 
 
-Use a robots.txt file
-~~~~~~~~~~~~~~~~~~~~~
+Use a robots.txt file ✅️
+~~~~~~~~~~~~~~~~~~~~~~~~~
 
 A ``robots.txt`` file is readable by crawlers
 and lives at the root of your site (eg. https://docs.readthedocs.io/robots.txt).
@@ -186,8 +231,8 @@ See the `Google's documentation on robots.txt <https://support.google.com/webmas
 for additional details.
 
 
-Use a sitemap.xml file
-~~~~~~~~~~~~~~~~~~~~~~
+Use a sitemap.xml file ✅️
+~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 A sitemap is a file readable by crawlers that contains a list of pages
 and other files on your site and some metadata or relationships about them
@@ -202,8 +247,8 @@ We have a small separate guide on :ref:`sitemaps <hosting:Sitemaps>`.
 See the `Google docs on building a sitemap <https://support.google.com/webmasters/answer/183668>`_.
 
 
-Use meta tags
-~~~~~~~~~~~~~
+Use meta tags ✅️
+~~~~~~~~~~~~~~~~~
 
 Using a meta description allows you to customize how your pages
 look in search engine result pages.

diff --git a/docs/user/index.rst b/docs/user/index.rst
@@ -88,6 +88,7 @@ to help you create fantastic documentation for your project.
    /science
    /commercial/organizations
    /automatic-redirects
+   /guides/technical-docs-seo-guide
 
 .. toctree::
    :maxdepth: 2