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

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

@@ -18,6 +18,8 @@ we explain some of the more specific or advanced concepts of writing documentati
 
 ⏩️ :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

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`.
 
-When we 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 :term:`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
 --------------------