Docs: New Explanation sub-levels + high-level introduction as explanation (Diátaxis)

docs/user/connected-accounts.rst

@@ -19,8 +19,8 @@ we recommend that you connect your Read the Docs account to your Git provider.
 Connecting your account allows for:
 
 * Easy import of your repositories.
-* Automatic configuration of your repository :doc:`/integrations`.
-  which allow Read the Docs to build your docs on every change to your repository
+* Automatic configuration of your repository's :term:`webhooks`.
+  which allows Read the Docs to build your docs on every change to your repository.
 * Logging into Read the Docs with your |git_providers_or| credentials.
 
 
@@ -71,7 +71,7 @@ Read the Docs does not generally ask for *write* permission to your repository c
 and since we only connect to public repositories we don't need special permissions to read them.
 However, we do need permissions for authorizing your account
 so that you can login to Read the Docs with your connected account credentials
-and to setup :doc:`/integrations`
+and to setup :term:`webhooks`
 which allow us to build your documentation on every change to your repository.
 
 

docs/user/environment-variables.rst

@@ -4,11 +4,11 @@ Understanding environment variables
 ===================================
 
 Read the Docs allows you to define your own environment variables to be used in the build process.
-It also defines a set of :doc:`default environment variables </reference/environment-variables>` with information about your build.
+It also defines a set of :doc:`pre-defined environment variables </reference/environment-variables>` with information about your build.
 These are useful for different purposes:
 
 * Custom environment variables are useful for adding build secrets such as API tokens.
-* Default environment variables are useful for varying your build specifically for Read the Docs or specific types of builds on Read the Docs.
+* Pre-defined environment variables are useful for varying your build specifically for Read the Docs or specific types of builds on Read the Docs.
 
 .. The following introduction is difficult to balance.
 .. We should ideally support environment variables in the Config File,

docs/user/explanation/advanced.rst

@@ -0,0 +1,29 @@
+Deep dive into Read the Docs
+============================
+
+In this section,
+we explain some of the more specific or advanced concepts of writing documentation on Read the Docs.
+
+⏩️ :doc:`/subprojects`
+    Thinking about gathering several documentation projects under the same umbrella?
+    This is a common need, and using *subprojects* is a flexible option that is recommended for most cases.
+
+⏩️ :doc:`/localization`
+    Learn more about multilingual documentation projects and how translation workflows are supported.
+
+⏩️ :doc:`/downloadable-documentation`
+    An introduction to adding downloadable files that can be read offline to your documentation and keep them versioned.
+
+⏩️ :doc:`/environment-variables`
+    Environment variables can be used to make your documentation builds flexible and easy to customize.
+    This is a general introduction to environment variables on our platform, both pre-defined and custom environment variables.
+
+
+.. toctree::
+   :maxdepth: 2
+   :hidden:
+
+   /subprojects
+   /localization
+   /downloadable-documentation
+   /environment-variables

docs/user/integrations.rst → docs/user/explanation/continuous-documentation.rst

@@ -7,28 +7,50 @@
 
 
 
-Continuous Documentation Deployment
-===================================
+Continuous Documentation
+========================
 
-Read the Docs is a *Continuous Documentation Deployment* platform for your software project.
-Every time you change something in your documentation, Read the Docs will detect your change and build your documentation.
+Read the Docs is a *Continuous Documentation* platform for your software project.
+Every time you change something in your documentation, Read the Docs will automatically detect your changes,
+*build* your documentation,
+and finally *deploy* your documentation for readers to see.
 
-The Continuous Integration and Continuous Deployment (CI/CD) features are configured with your repository provider,
-such as GitHub, Bitbucket or GitLab.
-With each change committed to your repository, we are notified by the configured *webhook*.
+The Continuous Integration and Continuous Deployment (:term:`CI/CD`) features are configured with your repository provider,
+such as |git_providers_or|.
+With each change committed to your repository, we are notified by the configured :term:`webhook <webhooks>`.
 
-When a receive a *webhook* notification, we match it to a project's *Integration*.
-When a webhook is received, the matching project will then:
+When a receive a *webhook* notification, we match it to a Read the Docs project.
+The matching project will then process your build and publish the documentation.
 
-* :doc:`Build </builds>` the latest commit.
-* Synchronize your versions based on the latest tag and branch data in Git.
-* Run your :doc:`automation rules</automation-rules>`.
-* Auto-cancel any currently running builds of the same version.
-* Add a log entry to the integration's :guilabel:`Recent Activity`.
+.. seealso::
+
+   :doc:`/builds`
+      Read more about the technical specification of the Build process and how you configure it.
+
+.. The short version
+.. -----------------
+
+.. If you follow for instance the tutorial,
+.. a simple setup will use our builders and deploy everything in the following way:
+
+.. 1. ...
+.. 2. ...
+.. 3. ...
+
+.. The long version
+.. ----------------
+
+.. * :doc:`Build </builds>` the latest commit.
+.. * Synchronize your versions based on the latest tag and branch data in Git.
+.. * Run your :doc:`automation rules</automation-rules>`.
+.. * Auto-cancel any currently running builds of the same version.
+.. * Add a log entry to the integration's :guilabel:`Recent Activity`.
 
 Continuous Documentation for software projects
 ----------------------------------------------
 
+.. TODO: This should be improved
+
 Documentation fits into any CI/CD pipeline by following a process known as *Documentation as Code (Docs as code)*.
 The primary method of doing this is by maintaining documentation alongside the source code,
 meaning that the documentation's life cycle is the same as your software project.
@@ -43,6 +65,11 @@ and increases overall value from the documentation you write.
 As part of this quick feedback loop,
 You can preview documentation changes immediately using :doc:`pull request previews </pull-requests>`.
 
+.. Continuous Documentation for scientific projects
+.. ------------------------------------------------
+
+.. We should perhaps write a short introduction here and reference the science page.
+
 Automated versioning
 --------------------