Docs: New how-to sublevels (Diátaxis)

docs/dev/style-guide.rst

@@ -187,9 +187,11 @@ This means that *both content and navigation path* for all sections should fit a
 Explanation
 ~~~~~~~~~~~
 
-* Introduce the scope: **“This article introduces ...”**
-  (write this as the very first thing,
-  then consider rewriting it or turning it into an internal comment afterwards).
+* Title convention: Use words indicating explanation in the title.
+  Like **Understanding <subject>**, **Dive into <subject>**, **Introduction to <subject>** etc.
+* Introduce the scope in the first paragraph: **“This article introduces ...”**.
+  Write this as the very first thing,
+  then re-read it and potentially shorten it later in your writing process.
 * Cross-reference the related How-to Guide.
   Put a ``seealso::`` somewhere visible.
   It should likely be placed right after the introduction,
@@ -200,9 +202,17 @@ Explanation
 How-to guides
 ~~~~~~~~~~~~~
 
-* Title should begin with **“How to ...”**,
-  but navigation titles should not contain the “How to” part.
+* Title should begin with **“How to ...”**.
+  If the how-to guide is specific for a tool, make sure to note it in the title.
+* Navigation titles should not contain the “How to” part.
+  Navigation title for "How to create a thing" is **Creating a thing**.
 * Introduce the scope: **“In this guide, we will…”**
+
+  * Introduction paragraph suggestions:
+
+    * "This guide shows <something>. <motivation>"
+    * "<motivation>. This guide shows you how."
+
 * Cross-reference related explanation.
   Put a ``seealso::`` somewhere visible,
   It should likely be placed right after the introduction
@@ -231,6 +241,7 @@ Tutorial
 
 .. note:: We don’t really have tutorials targeted in the systematic refactor, so this checklist isn’t very important right now.
 
+* "Getting started with <subject>" is likely a good start!
 * Cross-reference related explanation and how-to.
 * Try not to explain things too much, and instead link to the explanation content.
 * **Refactor other resources** so you can use references instead of disturbing the flow of the tutorial.

docs/user/connected-accounts.rst

@@ -1,7 +1,7 @@
 How to connect your Git repository
 ==================================
 
-In this article, we explain how connecting your Read the Docs account to one of the supported Git providers
+In this article, we explain how connecting your Read the Docs account to |git_providers_or|
 automatically configures your Git repository and your Read the Docs project.
 
 ✅️ Signed up with your Git provider?

docs/user/guides/access/index.rst

@@ -0,0 +1,39 @@
+How-to guides: security and access
+==================================
+
+⏩️ :doc:`Single Sign-On (SSO) with GitHub, GitLab, or Bitbucket </guides/setup-single-sign-on-github-gitlab-bitbucket>`
+    When using an :doc:`organization </commercial/organizations>` on  |com_brand|,
+    you can configure SSO for your users to authenticate to Read the Docs.
+
+⏩️ :doc:`Single Sign-On (SSO) with Google Workspace </guides/setup-single-sign-on-google-email>`
+    When using an :doc:`organization </commercial/organizations>` on  |com_brand|,
+    you can configure SSO for your users to authenticate to Read the Docs.
+    This guide is written for Google Workspace.
+
+⏩️ :doc:`Managing Read the Docs teams </guides/manage-read-the-docs-teams>`
+    When using an :doc:`organization </commercial/organizations>` on  |com_brand|,
+    it's possible to create different teams with custom access levels.
+
+⏩️ :doc:`Manually importing private repositories </guides/importing-private-repositories>`
+    You can grant access to private Git repositories using |com_brand| using a custom process if required.
+    Here is how you set it up.
+
+⏩️ :doc:`Using private Git submodules </guides/private-submodules>`
+    If you are using private Git repositories and they also contain private Git submodules,
+    you need to follow a few special steps.
+
+⏩️ :doc:`Installing private python packages </guides/private-python-packages>`
+    If you have private dependencies, you can install them from
+    a :ref:`private Git repository <guides/private-python-packages:From a Git repository>` or
+    a :ref:`private repository manager <guides/private-python-packages:From a repository manager other than PyPI>`.
+
+.. toctree::
+   :maxdepth: 1
+   :hidden:
+
+   Single Sign-On (SSO) with GitHub, GitLab, or Bitbucket </guides/setup-single-sign-on-github-gitlab-bitbucket>
+   Single Sign-On (SSO) with Google Workspace </guides/setup-single-sign-on-google-email>
+   Managing Read the Docs teams </guides/manage-read-the-docs-teams>
+   Manually importing private repositories </guides/importing-private-repositories>
+   Using private Git submodules </guides/private-submodules>
+   Installing private python packages </guides/private-python-packages>

docs/user/guides/best-practice/index.rst

@@ -0,0 +1,37 @@
+How-to guides: best practices
+=============================
+
+Over the years,
+we have become familiar with a number of methods that work well and which we consider **best practice**.
+
+⏩️ :doc:`Best practices for linking to your documentation </guides/best-practice/links>`
+    Documentation changes over time,
+    and links and cross-references can become challenging manage for various reasons.
+    Here is a set of best practices explaining and addressing these challenges.
+
+⏩️ :doc:`Deprecating content </guides/deprecating-content>`
+    Best practice for removing or deprecating documentation content.
+
+⏩️ :doc:`Creating reproducible builds </guides/reproducible-builds>`
+    Every documentation project has dependencies that are required to build it.
+    Using an unspecified versions of these dependencies means that your project can start breaking.
+    In this guide,
+    learn how to protect your project against breaking randomly.
+    **This is one of our most popular guides!**
+
+⏩️ :doc:`Search Engine Optimization (SEO) for documentation projects </guides/technical-docs-seo-guide>`
+    This article explains how documentation can be optimized to appear in search results,
+    increasing traffic to your docs.
+
+⏩️ :doc:`Hiding a version </guides/hiding-a-version>`
+    Learn how you can keep your entire version history online without overwhelming the reader with version choices.
+
+.. toctree::
+   :maxdepth: 1
+   :hidden:
+
+   Deprecating content </guides/deprecating-content>
+   Best practices for linking to your documentation </guides/best-practice/links>
+   Creating reproducible builds </guides/reproducible-builds>
+   Search Engine Optimization (SEO) for documentation projects </guides/technical-docs-seo-guide>
+   Hiding a version </guides/hiding-a-version>

docs/user/guides/build-troubleshooting.rst

@@ -1,8 +1,9 @@
-How to troubleshoote build errors
-=================================
+Troubleshooting build errors
+============================
 
 .. include:: /shared/contribute-to-troubleshooting.rst
 
+This guide provides some common errors and resolutions encountered in the :doc:`build process </builds>`.
 
 Git errors
 ----------

docs/user/guides/build-using-too-many-resources.rst

@@ -1,9 +1,13 @@
 Troubleshooting slow builds
 ===========================
 
+This page contains a list of the most common issues that are slowing down builds.
+
 In case you are waiting a long time for your builds to finish
 or your builds are terminated by exceeding general resource limits,
 this troubleshooting guide will help you resolve some of the most common issues causing slow builds.
+Even if you are not facing any immediate performance issues,
+it's always good to be familiar with the most common ones.
 
 Build resources on Read the Docs are limited to make sure that users don't overwhelm our build systems.
 The current build limits can be found on our :ref:`Build resources reference <builds:Build resources>`.

docs/user/guides/build/index.rst

@@ -0,0 +1,34 @@
+How-to guides: build process
+============================
+
+⏩️ :doc:`Setup build notifications and webhooks </guides/build-notifications>`
+    Build notifications can alert you when your builds fail so you can take immediate action.
+    In this guide,
+    you will learn how to get notified through various available channel integrations,
+    including email and chat.
+
+⏩️ :doc:`Configuring pull request builds </guides/pull-requests>`
+    Have your documentation built and access a preview for every :doc:`pull request builds </pull-requests>`.
+
+⏩️ :doc:`Using custom environment variables </guides/environment-variables>`
+    Extra environment variables, for instance secrets, may be needed in the build process and can be defined from the project's :term:`dashboard`.
+
+⏩️ :doc:`Managing versions automatically </guides/automation-rules>`
+    Automating your versioning on Read the Docs means you only have to handle your versioning logic in Git.
+    Learn how to define rules to automate creation of new versions on Read the Docs,
+    entirely using your Git repository's version logic.
+
+
+.. seealso:
+
+   :doc:`/builds`
+      An overview and introduction to the build process.
+
+.. toctree::
+   :maxdepth: 1
+   :hidden:
+
+   Setup build notifications and webhooks </guides/build-notifications>
+   Configuring pull request builds </guides/pull-requests>
+   Using custom environment variables </guides/environment-variables>
+   Managing versions automatically </guides/automation-rules>

docs/user/guides/content/index.rst

@@ -0,0 +1,82 @@
+How-to guides: content, themes and SEO
+======================================
+
+⏩️ :doc:`Search Engine Optimization (SEO) for documentation projects </guides/technical-docs-seo-guide>`
+    This article explains how documentation can be optimized to appear in search results,
+    ultimately increasing traffic to your docs.
+
+⏩️ :doc:`Enabling canonical URLs </guides/canonical-urls>`
+    In this guide, we introduce relevant settings for enabling canonical URLs in popular documentation frameworks.
+
+⏩️ :doc:`Using traffic analytics </analytics>`
+    In this guide, you can learn to use Read the Docs' built-in traffic analytics for your documentation project.
+    You will also learn how to optionally add your own Google Analytics account or completely disable Google Analytics on your project.
+
+⏩️ :doc:`Managing translations for Sphinx projects </guides/manage-translations-sphinx>`
+    This guide walks through the process needed to manage translations of your documentation.
+    Once this work is done, you can setup your project under Read the Docs to build each language of your documentation by reading :doc:`/localization`.
+
+⏩️ :doc:`Supporting Unicode in Sphinx PDFs </guides/pdf-non-ascii-languages>`
+    Sphinx offers different LaTeX engines that have better support for Unicode characters, relevant for instance for Japanese or Chinese.
+
+⏩️ :doc:`Cross-referencing with Sphinx </guides/cross-referencing-with-sphinx>`
+    When writing documentation you often need to link to other pages of your documentation,
+    other sections of the current page, or sections from other pages.
+
+⏩️ :doc:`Linking to other projects with Intersphinx </guides/intersphinx>`
+    This section shows you how to maintain references to named sections of other external Sphinx projects.
+
+⏩️ :doc:`Using Jupyter notebooks in Sphinx </guides/jupyter>`
+    There are a few extensions that allow integrating Jupyter and Sphinx,
+    and this document will explain how to achieve some of the most commonly requested features.
+
+⏩️ :doc:`Migrating from rST to MyST </guides/migrate-rest-myst>`
+    In this guide, you will find
+    how you can start writing Markdown in your existing reStructuredText project,
+    or migrate it completely.
+
+⏩️ :doc:`Enabling offline formats </guides/enable-offline-formats>`
+    This guide provides step-by-step instructions to enabling offline formats of your documentation.
+
+⏩️ :doc:`Using search analytics </guides/search-analytics>`
+    In this guide, you can learn to use Read the Docs' built-in search analytics for your documentation project.
+
+⏩️ :doc:`Adding custom CSS or JavaScript to Sphinx documentation </guides/adding-custom-css>`
+    Adding additional CSS or JavaScript files to your Sphinx documentation
+    can let you customize the look and feel of your docs
+    or add additional functionality.
+
+⏩️ :doc:`Embedding content from your documentation </guides/embedding-content>`
+    Did you know that Read the Docs has a public API that you can use to embed documentation content?
+    There are a number of use cases for embedding content,
+    so we've built our integration in a way that enables users to build on top of it.
+
+⏩️ :doc:`Removing "Edit on ..." buttons from documentation </guides/remove-edit-buttons>`
+    When building your documentation,
+    Read the Docs automatically adds buttons at the top of your documentation and in the versions menu that point readers to your repository to make changes.
+    Here's how to remove it.
+
+⏩️ :doc:`Adding "Edit Source" links on your Sphinx theme </guides/edit-source-links-sphinx>`
+    Using your own theme?
+    Read the Docs injects some extra variables in the Sphinx ``html_context``,
+    some of which you can use to add an "edit source" link at the top of all pages.
+
+.. toctree::
+   :maxdepth: 1
+   :hidden:
+
+   Search Engine Optimization (SEO) for documentation projects </guides/technical-docs-seo-guide>
+   Using traffic analytics </analytics>
+   Using search analytics </guides/search-analytics>
+   Enabling canonical URLs </guides/canonical-urls>
+   Enabling offline formats </guides/enable-offline-formats>
+   Embedding content from your documentation </guides/embedding-content>
+   Managing translations for Sphinx projects </guides/manage-translations-sphinx>
+   Supporting Unicode in Sphinx PDFs </guides/pdf-non-ascii-languages>
+   Cross-referencing with Sphinx </guides/cross-referencing-with-sphinx>
+   Linking to other projects with Intersphinx </guides/intersphinx>
+   Using Jupyter notebooks in Sphinx </guides/jupyter>
+   Migrating from rST to MyST </guides/migrate-rest-myst>
+   Adding custom CSS or JavaScript to Sphinx documentation </guides/adding-custom-css>
+   Removing "Edit on ..." buttons from documentation </guides/remove-edit-buttons>
+   Adding "Edit Source" links on your Sphinx theme </guides/edit-source-links-sphinx>

docs/user/guides/deprecating-content.rst

@@ -13,7 +13,7 @@ progressively and in non harmful ways.
 
 .. seealso::
 
-   :doc:`/automatic-redirects`
+   :doc:`/guides/best-practice/links`
      More information about handling URL structures, renaming and removing content.
 
 Deprecating versions

docs/user/guides/embedding-content.rst

@@ -5,7 +5,7 @@ Read the Docs allows you to embed content from any of the projects we host and s
 (currently, ``docs.python.org``, ``docs.scipy.org``, ``docs.sympy.org``, ``numpy.org``)
 This allows reuse of content across sites, making sure the content is always up to date.
 
-There are a number of uses cases for embedding content,
+There are a number of use cases for embedding content,
 so we've built our integration in a way that enables users to build on top of it.
 This guide will show you some of our favorite integrations:
 

docs/user/guides/git-integrations.rst

@@ -1,7 +1,9 @@
 How to manually connect your Git repository
 ===========================================
 
-In this guide, you will find the simple steps to integrating your Read the Docs project with GitHub, Bitbucket, GitLab, Gitea or any other Git provider that supports our generic API.
+In this guide,
+you will find the simple steps to manually integrating your Read the Docs project with all Git providers that supports our generic API.
+This includes most Git providers, for example |git_providers_and|.
 
 .. note::
 

docs/user/guides/importing-private-repositories.rst

@@ -8,6 +8,9 @@ How to import private repositories
    we recommend :doc:`connecting your account </connected-accounts>` and importing your project from
    https://readthedocs.com/dashboard/import instead of importing it manually.
 
+You can grant access to private Git repositories using |com_brand|.
+Here is how you set it up.
+
 If you are using an unsupported integration, or don't want to connect your account,
 you'll need to do some **extra steps in order to have your project working**.