Docs: Split configuration file v2

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/explanation/advanced.rst

@@ -4,6 +4,11 @@ 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.
@@ -23,6 +28,7 @@ we explain some of the more specific or advanced concepts of writing documentati
    :maxdepth: 2
    :hidden:
 
+   /config-file/index
    /subprojects
    /localization
    /downloadable-documentation

docs/user/index.rst

@@ -41,7 +41,7 @@ Read the Docs: documentation simplified
    :caption: 📚 Reference
 
    /reference/features
-   /config-file/index
+   /config-file/v2
    /builds
    /build-customization
    /server-side-search/syntax
@@ -160,7 +160,7 @@ Need to know how something works? Our references provide the details:
 📚 :doc:`/reference/features`
   Overview of all the main features of Read the Docs.
 
-📚 :doc:`/config-file/index`
+📚 :doc:`/config-file/v2`
   Information for our configuration file: ``.readthedocs.yaml``.
 
 📚 :doc:`/builds`

docs/user/versions.rst

@@ -12,7 +12,7 @@ we also create a ``stable`` version, tracking your most recent release.
 If you want a custom ``stable`` version,
 create either a tag or branch in your project with that name.
 
-When you have :term:`webhook <webhooks>` configured for your repository,
+When you have :term:`webhook` configured for your repository,
 we will automatically build each version when you push a commit.
 
 How we envision versions working