Docs: Configuration file pages as explanation and reference (Diátaxis)

docs/user/config-file/index.rst

@@ -1,27 +1,66 @@
-Configuration file
-==================
+.. TODO: Use new glossary terms added in another PR
 
-In addition to using the admin panel of your project to configure your project,
-you can use a configuration file in the root of your project.
-The configuration file should be named ``.readthedocs.yaml``.
+Versioning your configuration
+=============================
 
-.. note::
+The lifecycle of a documentation project changes the content and the structure of the documentation.
+In addition to this,
+**the whole configuration of a project also changes**.
 
-   Some other variants like ``readthedocs.yaml``, ``.readthedocs.yml``, etc
-   are deprecated.
+But changing your configuration for your documentation's version 2.x should not make it impossible to keep maintaining the documentation for version 1.x using a previous configuration.
+
+.. seealso::
+
+   :doc:`/config-file/v2`
+      Reference of all the settings offered in the build configuration file.
+
+Consider the following aspects of a documentation project:
+
+:Build environment:
+    You may depend on a number of packages but your method for installing them changes.
+    What is installed, how it's installed and what installs it can change.
+
+    For instance,
+    you might change between Pip, Pipenv, Conda etc.
+
+    You might also jump between Python 2 and 3 or Python 3.8 and Python 3.10.
+
+:Documentation tools:
+    Using Sphinx? Using MkDocs? Or some other tool?
+    All these tools have their own configuration files and special ways to invoke them.
+
+    Changing the documentation tool should also be possible in the lifecycle of your documentation.
+    Read the Docs understands outputs from several different documentation tools and therefore,
+    it's possible to change documentation tools between different versions of documentation.
+
+
+You can configure your Read the Docs project by adding a special file ``.readthedocs.yaml`` [1]_ to your Git repository.
+
+Because the file is stored in Git,
+the configuration will apply to the exact version that is being built.
+This allows you to store different configurations for different versions of your documentation.
 
 The main advantages of using a configuration file over the web interface are:
 
 - Settings are per version rather than per project.
-- Settings live in your VCS.
+- Settings live in your Git repository.
 - They enable reproducible build environments over time.
 - Some settings are only available using a configuration file
 
-.. tip::
+.. [1] Other variants of the configuration file name like ``readthedocs.yaml``, ``.readthedocs.yml``, etc. are deprecated.
+
+Configuration as Code
+---------------------
+
+"Configuration as Code" is a concept whereby the configuration or settings of software is maintained in a Git repository as *code*.
+Alternatively, configurations are often added and managed inside the software's own UI,
+making it hard to track changes, and reproduce and copy behavior to other projects.
 
-   Using a configuration file is the recommended way of using Read the Docs.
+Because of its fragility and uniqueness,
+the alternative to "Configuration as Code" is also often referred to as snowflake ❄️ configuration.
 
-.. toctree::
-    :maxdepth: 3
+.. seealso::
 
-    Version 2 <v2>
+   :doc:`/guides/reproducible-builds`
+      In addition to storing your configuration in Git,
+      we also recommend special practices for making your builds resilient to changes in your software dependencies.

docs/user/config-file/v2.rst

@@ -1,11 +1,15 @@
-Configuration file v2
-=====================
+Configuration file .readthedocs.yaml
+====================================
 
 Read the Docs supports configuring your documentation builds with a YAML file.
-The :doc:`configuration file <index>` must be in the root directory of your project
-and be named ``.readthedocs.yaml``.
+It's required to be named ``.readthedocs.yaml`` and be placed in the root of your Git repository.
+
+The file can contain a number of settings that are not accessible through the Read the Docs website.
+
+Because the file is stored in Git,
+the configuration will apply to the exact version that is being built.
+This allows you to store different configurations for different versions of your documentation.
 
-All options are applied to the version containing this file.
 Below is an example YAML file which shows the most common configuration options:
 
 .. tabs::
@@ -942,3 +946,23 @@ These settings aren't supported via the configuration file.
 * ``Show versions warning``
 * ``Privacy level``
 * ``Analytics code``
+
+Custom sub-folder for .readthedocs.yaml
+---------------------------------------
+
+In order to support *monorepo* layouts,
+it's possible to configure the sub-folder where your ``.readthedocs.yaml`` is found.
+
+Using this configuration makes it possible to create several Read the Docs projects pointing at the same Git repository.
+This is recommended for monorepo layouts that host several documentation projects in the same repository.
+
+.. seealso::
+
+   :doc:`/guides/setup/monorepo`
+      This guide explains how to use the configuration.
+
+Previous version: v1
+--------------------
+
+Version 1 is deprecated and using it is discouraged,
+view its reference here :doc:`/config-file/v2`.

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 <webhook>`.
+  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 <webhook>`
 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,35 @@
+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:`/config-file/index`
+    Configure your documentation build in a configuration file stored in Git:
+    The lifecycle of a documentation project changes the content and the structure of the documentation.
+    In addition to this, **the whole configuration of a project also changes**.
+
+⏩️ :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:
+
+   /config-file/index
+   /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`.
 
-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
 --------------------